qnx neutrinosanprotechwriting.com/software/user_guide.pdfconﬁguration issues, see the welcome to...

QNX Neutrino RTOS

User’s Guide

For release 6.3 or later

QNX Software Systems Ltd.175 Terence Matthews CrescentKanata, OntarioK2M 1W8CanadaVoice: 613-591-0931Fax: 613-591-3579Email: [email protected]: http://www.qnx.com/

QNX Software Systems Ltd. 2003. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic,mechanical, photocopying, recording, or otherwise without the prior written permission of QNX Software Systems Ltd.

Although every precaution has been taken in the preparation of this book, we assume no responsibility for any errors or omissions, nordo we assume liability for damages resulting from the use of the information contained in this book.

Publishing history

December 2003 First edition

QNX, Momentics, Neutrino, and Photon are registered trademarks of QNX Software Systems Ltd. All other trademarks and registered trademarks belong to

their respective owners.

Printed in Canada.

Part Number: @@@

Contents

About This Guide ixTypographical conventions xi

What you’ll find in this guide xiii

Note to Windows users xv

Assumptions xv

Working with Filesystems 11Introduction 3

Setting up, starting, and stopping a block filesystem 3

Mounting and unmounting filesystems 4

Image filesystem 4

Configuring an OS image 5

/dev/shmem RAM “filesystem” 5

QNX 4 filesystem 6

Disk structure 7

Filesystem robustness 15

DOS filesystem 15

CD-ROM filesystem 16

Linux Ext2 filesystem 16

Flash filesystems 17

CIFS filesystem 18

NFS filesystem 19

Setting up NFS 19

NFS server 20

NFS client 21

Contents iii

Package filesystem 22

Packages in their repositories 22

Spill directory 25

Underlying filesystem 26

Control files 27

Patches 27

Inflator filesystem 28

Troubleshooting 28

Transparent Networking via Qnet 292What is Qnet? 31

Qnet or TCP/IP? 31

Conventions for naming nodes 33

Software components for Qnet networking 34

Starting Qnet 36

Creating useqnet 36

Starting the network manager, protocols, and drivers 37

Checking out the neighborhood 37

Troubleshooting 38

Is Qnet running? 39

Are io-net and the drivers running? 39

Is the Qnet protocol stack or ethernet driver installed? 40

Is the network card functional? 40

How do I get diagnostic information? 41

Is the Qnet version correct? 42

Is the host name unique? 42

TCP/IP Networking 433Overview of TCP/IP 45

Clients and servers 45

Hosts and gateways 45

Nameservers 46

Routing 47

iv Contents

Software components for TCP/IP networking 48

Choosing the right stack configuration 49

Tiny stack (npm-ttcpip.so) 50

Full TCP/IP stack (npm-tcpip.so) 51

Running the Internet daemons 52

Running multiple instances of the TCP/IP stack 54

Using the Point-to-Point Protocol over Ethernet (PPPoE) 55

Using the SRI SNMP suite for QNX Neutrino 57

Troubleshooting 57

Are io-net and the drivers running? 58

Is TCP/IP protocol stack or ethernet driver installed? 59

What is the nameserver information? 59

How do I map host names to IP addresses? 59

How do I get the network status? 60

How do I make sure I’m connected to other hosts? 60

How do I display information about an interface controller?61

Examples 63ABuildfile for an NFS-mounting host 65

qnxbasedma.build 68

.profile 70

.kshrc 70

Configuration files for spooler 71

Using lpr 71

Using NCFTP 73

Using SAMBA 74

Configuration files for setting up a firewall 76

ipf.conf.sample 76

ipnat.conf 77

Glossary 79

Contents v

Index 103

vi Contents

List of Figures

A file with multiple extents. 9

One file referenced by two links. 11

Symbolic links. 14

Actual filesystem using the package filesystem. 23

Virtual filesystem using the package filesystem. 24

Working with the spill directory. 26

Components of Qnet. 35

Components of TCP/IP 49

List of Figures vii

About This Guide

About This Guide ix

Typographical conventions

Typographical conventionsThroughout this manual, we use certain typographical conventions todistinguish technical terms. In general, the conventions we useconform to those found in IEEE POSIX publications. The followingtable summarizes our conventions:

Reference Example

Code examples if( stream == NULL )

Command options -lR

Commands make

Environment variables PATH

File and pathnames /dev/null

Function names exit()

Keyboard chords Ctrl – Alt – Delete

Keyboard input something you type

Keyboard keys Enter

Program output login:

Programming constants NULL

Programming data types unsigned short

Programming literals 0xFF, "message string"

Variable names stdin

User-interface components Cancel

We format single-step instructions like this:

➤ To reload the current page, press Ctrl – R.

We use an arrow (→) in directions for accessing menu items, like this:

About This Guide xi

Typographical conventions

You’ll find the Other... menu item underPerspective→Show View.

We use notes, cautions, and warnings to highlight importantmessages:

Notes point out something important or useful.�

CAUTION: Cautions tell you about commands or procedures thatmay have unwanted or undesirable side effects.

WARNING: Warnings tell you about commands or proceduresthat could be dangerous to your files, your hardware, or evenyourself.

xii About This Guide

What you’ll find in this guide

What you’ll find in this guideThe Neutrino User’s Guide tells you how to:

� Use the QNX Neutrino runtime environment, regardless of thekind of computer it’s running on (embedded system or desktop).Think of this guide as the companion how-to doc for the UtilitiesReference. Assuming there’s a QNX Neutrino system prompt orPhoton login waiting for input, this guide is intended to help youlearn how to interact with that prompt.

� Perform such traditional system administration topics as setting upuser accounts, security, mail, etc.

For information about installation, licensing, and other “first-time”configuration issues, see the Welcome to QNX Momentics guide.

�

The QNX Neutrino User’s Guide is intended for programmers whodevelop QNX Neutrino-based applications, as well as OEMs andother “resellers” of the OS, who may want to pass this guide on totheir end users as a way to provide documentation for the OScomponent of their product.

The following table may help you find information quickly:

To find out about: Go to:

How Neutrino compares toother operating systems

Getting to Know the OS

Starting and ending a sessionon, and turning off, a Neutrinosystem

Logging In, Logging Out, andShutting Down

Adding users to the system,managing passwords, etc.

Managing User Accounts

continued. . .

About This Guide xiii

What you’ll find in this guide


The basics of using thekeyboard, command line, andshell (command interpreter)

Using the Command Line

Using Neutrino’s graphical userinterface

Using the Photon microGUI

Files, directories, andpermissions

Working with Files

How to edit files Using Editors

Configuring what your machinedoes when it boots

Starting Up Your System

Customizing your shell, settingthe time, etc.

Configuring Your Environment

Creating your own commands Writing Shell Scripts

The filesystems that Neutrinosupports

Working with Filesystems

Accessing other machines withNeutrino’s native networking

Transparent Networking viaQnet

Setting up TCP/IP TCP/IP Networking

Adding printers to your systemand using them

Printing

Adding USB devices, terminals,video cards, and other hardwareto your system

Connecting Hardware

Adding embedded HTTPservices and dynamic content toembedded web applications

Setting Up an Embedded WebServer

Repositories and packages Installing and RemovingSoftware

continued. . .

xiv About This Guide

Note to Windows users


Keeping track of changes toyour software and other files

Using CVS

Backing up and restoring yourfiles

Recovering Lost Data

Making your Neutrino systemmore secure

Securing Your System

Analyzing and improving yourmachine’s performance

Fine-Tuning Your System

How many processes, files, etc.your system can support

Understanding System Limits

How to get help Technical Support

Samples of buildfiles, profiles,etc.

Examples

Terms used in QNX docs Glossary

Note to Windows usersIn QNX documentation, we use a forward slash (/) as a delimiter inall pathnames, including those pointing to Windows files.

We also generally follow POSIX/UNIX filesystem conventions.

Assumptions� We assume that QNX Neutrino is already installed and running on

your computer.

� This guide is intended for all users of a QNX Neutrino system,from system administrators to end users.

� The online version of this guide contains links to various booksthroughout our entire documentation set; if you don’t have theentire set installed on your system, you’ll naturally get somebad-link errors (e.g. “HTTP 404 - File not found”).

About This Guide xv

Chapter 1

Working with Filesystems

In this chapter. . .Introduction 3Setting up, starting, and stopping a block filesystem 3Mounting and unmounting filesystems 4Image filesystem 4/dev/shmem RAM “filesystem” 5QNX 4 filesystem 6DOS filesystem 15CD-ROM filesystem 16Linux Ext2 filesystem 16Flash filesystems 17CIFS filesystem 18NFS filesystem 19Package filesystem 22Inflator filesystem 28Troubleshooting 28

Chapter 1 � Working with Filesystems 1

Introduction

IntroductionQNX Neutrino provides a variety of filesystems, so that you caneasily access DOS, Linux, as well as native (QNX 4) disks. TheFilesystems chapter of the System Architecture guide describes theirclasses and features.

The System Architecture guide sometimes describes features thathaven’t yet been implemented. For example, io-cam doesn’t exist asa process; the devb-* drivers are still processes instead of sharedobjects.

�

Under Neutrino:

� You can dynamically start and stop filesystems.

� Multiple filesystems may run concurrently.

� Applications are presented with a single unified pathname spaceand interface, regardless of the configuration and number ofunderlying filesystems.

The system starts the appropriate block filesystems on booting; youstart other filesystems as standalone managers. The default blockfilesystem is the QNX 4 filesystem.

Setting up, starting, and stopping a blockfilesystemWhen you boot your machine, the system detects partitions on theblock I/O devices and automatically starts the appropriate filesystemfor each partition (see Starting Up Your System).

You aren’t likely ever to need to stop or restart a block filesystem; ifyou change any of the filesystem’s options, you can use the -e or -uoption to the mount command to update the filesystem.

If you need to change any of the options associated with the block I/Odevice, you can slay the appropriate devb-* driver (being careful not


Mounting and unmounting filesystems

to pull the carpet from under your feet) and restart it, but you’ll needto mount any of the filesystems on it explicitly.

Mounting and unmounting filesystemsThe following utilities work with filesystems:

mount Mount a block-special device or remote filesystem.

umount Unmount a device or filesystem.

For example, if fs-cifs is already running, you can mountfilesystems on it like this:

mount -t cifs -o guest,none //SMB SERVER:10.0.0.1:/QNX BIN /bin

See the Utilities Reference for details on usage and syntax.

Image filesystemBy an image, we refer to an OS image here, which is a file thatcontains the OS, your executables, and any data files that might berelated to your programs, for use in an embedded system. You canthink of the image as a small “filesystem” — it has a directorystructure and some files in it.

The image contains a small directory structure that tells procnto thenames and positions of the files contained within it; the image alsocontains the files themselves. When the embedded system is running,the image can be accessed just like any other read-only filesystem:

# cd /proc/boot# ls.script cat data1 data2 devc-ser8250esh ls procnto# cat data1This is a data file, called data1, contained in the image.Note that this is a convenient way of associating datafiles with your programs.

4 Chapter 1 � Working with Filesystems

/dev/shmem RAM “filesystem”

The above example actually demonstrates two aspects of having theOS image function as a filesystem. When we issue the ls command,the OS loads ls from the image filesystem (pathname/proc/boot/ls). Then, when we issue the cat command, the OSloads cat from the image filesystem as well, and opens the filedata1.

Configuring an OS imageYou can create an OS image by using mkifs (make imagef ilesystem). This utility accepts information from two main sources:its command line and a buildfile. For more information, see BuildingEmbedded Systems, and mkifs in the Utilities Reference.

/dev/shmem RAM “filesystem”QNX Neutrino provides a simple RAM-based filesystem that allowsread/write files to be placed under /dev/shmem. This filesystem isn’ta true filesystem because it lacks features such as subdirectories. Italso doesn’t include . and .. entries for the current and parentdirectories.

The files in the /dev/shmem directory are advertised as“name-special” files (S IFNAME), which fools many utilities — suchas gzip and more — that expect regular files (S IFREG). For thisreason, many utilities might not work for the RAM filesystem.

This filesystem is mainly used by the shared memory system ofprocnto. In special situations, you can use the RAM filesystem tostore file data. Use this filesystem when there’s no filesystemavailable, and you need to store file data. There’s nothing to stop a filefrom consuming all free RAM. If this happens, other processes mighthave problems.

You’ll use the RAM filesystem mostly in tiny embedded systemswhere you need a small, fast, temporary-storage filesystem, but youdon’t need persistent storage across reboots.


QNX 4 filesystem

The filesystem comes for free with procnto and doesn’t require anysetup or device driver. You can simply create files under /dev/shmemand grow them to any size (depending on RAM resources).

Although the RAM filesystem itself doesn’t support hard or soft linksor directories, you can create a link to it by using process-managerlinks. For example, you could create a link to a RAM-based /tmpdirectory:

ln -sP /dev/shmem /tmp

This tells procnto to create a process-manager link to /dev/shmem

known as /tmp. Most application programs can then open files under/tmp as if it were a normal filesystem.

In order to minimize the size of the RAM filesystem code inside theprocess manager, this filesystem specifically doesn’t include “bigfilesystem” features such as file locking and directory creation.

�

QNX 4 filesystemThe QNX 4 filesystem — the default for QNX Neutrino — uses thesame on-disk structure as in the QNX 4 operating system. Thisfilesystem is implemented by the fs-qnx4.so shared object and isautomatically loaded by the devb-* drivers when mounting a QNX 4filesystem.

You can create a QNX disk partition by using the fdisk utility.

This filesystem implements an extremely robust design, utilizing anextent-based, bitmap allocation scheme with fingerprint controlstructures to safeguard against data loss and to provide easy recovery.Features include:

� extent-based POSIX filesystem

� robustness: all sensitive filesystem info is written through to disk

� on-disk “signatures” and special key information to allow fast datarecovery in the event of disk damage


QNX 4 filesystem

� 505-character filenames

� multi-threaded design

� client-driven priority

� same disk format as the filesystem under QNX 4

� support for files up to 2G − 1 byte.

Disk structureThe QNX 4 filesystem consists of the following components found atthe beginning of its partition:

� loader block

� root block

� bitmap

� root directory

� other directories, files, free blocks, etc.

These structures are created when you initialize the filesystem withthe dinit utility.

Loader block

This is the first physical block of a disk partition. This block containsthe code that is loaded and then executed by the BIOS of the computerto load an OS from the partition. If a disk hasn’t been partitioned (e.g.a floppy diskette), this block is the first physical block on the disk.

Root block

The root block is structured as a standard directory. It contains inodeinformation for these special files:

� the root directory of the filesystem (/)

� /.inodes


QNX 4 filesystem

� /.boot

� /.altboot

The files /.boot and /.altboot contain images of the operatingsystem that can be loaded by the QNX bootstrap loader.

Normally, the QNX loader loads the OS image stored in the /.bootfile. But if the /.altboot file isn’t empty, you’ll be given the optionto load the image stored in the /.altboot file. For moreinformation, see Starting Up Your System.

Bitmap

To allocate space on a disk, the OS uses a bitmap stored in the/.bitmap file. This file contains a map of all the blocks on the disk,indicating which blocks are used. Each block is represented by a bit.If the value of a bit is 1, its corresponding block on the disk is in use.

Root directory

The root directory of a partition behaves as a normal directory filewith two exceptions:

� Both “dot” (.) and “dot dot” (..) are links to the same inodeinformation, namely the root directory inode in the root block.

� The root directory always has entries for the /.bitmap,/.inodes, /.boot, and /.altboot files. These entries areprovided so programs that report information on filesystem usagesee the entries as normal files.

Extents

In the QNX filesystem, regular files and directory files are stored as asequence of extents, contiguous sequences of blocks on a disk.

Files that have only a single extent store the extent information in thedirectory entry. If more than one extent is needed to hold the file, theextent location information is stored in one or more linked extentblocks. Each extent block can hold location information for up to 60extents.


QNX 4 filesystem

Directoryentry

Extentblock

First extent Second extent Last extent

.

.

.

...

A file with multiple extents.

Extending files

When the filesystem needs to extend a file, it uses the bitmap to see ifit can extend the file contiguously on disk. If not, it tries to allocate anew extent. This may require allocating a new extent block as well.When an extent is allocated or grown, the filesystem mayover-allocate space under the assumption that the process willcontinue to write and fill the extra space. When the file is closed, anyextra space is returned.

This design ensures that when files are written, even several files atone time, they are as contiguous as possible. Since most hard diskdrives implement track caching, this not only ensures that files areread as quickly as possible from the disk hardware, but also serves tominimize the fragmentation of data on disk.

For more information about performance, see Fine-Tuning YourSystem.


QNX 4 filesystem

File names

The original QNX 4 filesystem supported filenames of no more than48 characters long. This limit has now increased to 505 characters viaa backwards-compatible extension that’s enabled by default. Thesame on-disk format is retained; new systems see the longer name,but old ones see a truncated 48-character name.

To enable support for long filenames on a new QNX 4 filesystem,specify the -N option to dinit. To add long filename support to anexisting QNX 4 filesystem, login as root and create an empty,read-only file named .longfilenames, owned by root in the rootdirectory of the filesystem:

cd root dirtouch .longfilenameschmod a=r .longfilenameschown root:root .longfilenames

After creating the .longfilenames file, you must restart thefilesystem for it to enable long filenames.

�

You can determine the maximum filename length that a filesystemsupports by using the getconf utility:

getconf PC NAME MAX root dir

where root dir is the root directory of the filesystem.

You can’t use the characters 0x00-0x1F, 0x7F, and 0xFF infilenames. In addition, / (0x2F) is the pathname separator, and can’tbe in a filename component. You can use spaces, but you have to“quote” them on the command line; you also have to quote anywildcard characters that the shell supports. For more information, see“Quoting special characters” in Using the Command Line.


QNX 4 filesystem

Links and inodes

File data is stored distinctly from its name and can be referenced bymore than one name. Each filename, called a link, points to the actualdata of the file itself. (There are actually two kinds of links: hardlinks, which we refer to simply as “links,” and symbolic links, whichare described in the next section.)

In order to support links for each file, the filename is separated fromthe other information that describes a file. The non-filenameinformation is kept in a storage table called an inode (for “informationnode”).

If a file has only one link (i.e. one filename), the inode information(i.e. the non-filename information) is stored in the directory entry forthe file. If the file has more than one link, the inode is stored as arecord in a special file named /.inodes — the file’s directory entrypoints to the inode record.

File contents

/bin

ls

more

less

/.inodes

File contents

One file referenced by two links.

Note that you can create a link to a file only if the file and the link arein the same filesystem.

There are two other situations in which a file can have an entry in the/.inodes file:


QNX 4 filesystem

� If a file’s filename is longer than 16 characters (but less than orequal to 48), the inode information is stored in the /.inodes file,making room for a 48-character filename in the directory entry.Filenames greater than 48 characters are stored within a.longfilenames file, which has room for a 505-character name;a truncated 48-character name is also placed in .inodes for useby legacy systems.

� If a file had more than one link, and all links but one have beenremoved, the file continues to have a separate /.inodes file entry.This is done because the overhead of searching for the directoryentry that points to the inode entry would be prohibitive (there areno back links from inode entries to directory entries).

Removing links

When a file is created, it is given a link count of one. As links to thefile are added, this link count is incremented; as links are removed,the link count is decremented. The disk space occupied by the filedata isn’t freed and marked as unused in the bitmap until its link countgoes to zero and all programs using the file have closed it. Thisallows an open file to remain in use, even though it has beencompletely unlinked. This behavior is part of that stipulated byPOSIX and common UNIX practice.

Directory links

Although you can’t create hard links to directories, each directory hastwo hard-coded links already built in:

. (“dot”)

.. (“dot dot”)

The filename “dot” refers to the current directory; “dot dot” refers tothe previous (or parent) directory in the hierarchy.

Note that if there’s no predecessor, “dot dot” also refers to the currentdirectory. For example, the “dot dot” entry of / is simply / — youcan’t go further up the path.


QNX 4 filesystem

There’s no POSIX requirement for a filesystem to include . or ..entries; some filesystems, including flash filesystems anddev/shmem, don’t.

�

Symbolic links

A symbolic link is a special file that usually has a pathname as itsdata. When the symbolic link is named in an I/O request — byopen(), for example — the link portion of the pathname is replaced bythe link’s “data” and the path is reevaluated.

Symbolic links are a flexible means of pathname indirection and areoften used to provide multiple paths to a single file. Unlike hard links,symbolic links can cross filesystems and can also create links todirectories.

In the following example, the directories /net/node1/usr/fredand /net/node2/usr/barney are linked even though they resideon different filesystems — they’re even on different nodes (see thefollowing diagram). You can’t do this using hard links:

/net/node1/usr/fred → /net/node2/usr/barney

Note how the symbolic link and the target directory need not share thesame name. In most cases, you use a symbolic link for linking onedirectory to another directory. However, you can also use symboliclinks for files, as in this example:

/net/node1/usr/eric/src/sample.c → /net/node1/usr/src/game.c


QNX 4 filesystem

Node 1 Node 2

Symboliclink

/usr

barney sam

hello.c my_file

/usr

eric src fred

sample.c

game.cSymbolic

link

src

Symbolic links.

Removing a symbolic link deletes only the link, not the target.�

Several functions operate directly on the symbolic link. For thesefunctions, the replacement of the symbolic element of the pathnamewith its target is not performed. These functions include unlink()(which removes the symbolic link), lstat(), and readlink().

Since symbolic links can point to directories, incorrect configurationscan result in problems such as circular directory links. To recoverfrom circular references, the system imposes a limit on the number ofhops; this limit is defined as SYMLOOP MAX in the <limits.h>include file.


DOS filesystem

Filesystem robustnessThe QNX 4 filesystem achieves high throughput without sacrificingreliability. This has been accomplished in several ways.

While most data is held in the buffer cache and written after only ashort delay, critical filesystem data is written immediately. Updates todirectories, inodes, extent blocks, and the bitmap are forced to disk toensure that the filesystem structure on disk is never corrupt (i.e. thedata on disk should never be internally inconsistent).

Sometimes all of the above structures must be updated. For example,if you move a file to a directory and the last extent of that directory isfull, the directory must grow. In such cases, the order of operationshas been carefully chosen such that if a catastrophic failure (e.g. apower failure) occurs when the operation is only partially completed,the filesystem, upon rebooting, would still be “intact.” At worst, someblocks may have been allocated, but not used. You can recover thesefor later use by running the chkfsys utility.

DOS filesystemThe DOS filesystem provides transparent access to DOS disks, so youcan treat DOS filesystems as though they were QNX Neutrino(POSIX) filesystems. This transparency lets processes operate onDOS files without any special knowledge or work on their part.

The fs-dos.so shared object (see the Utilities Reference) lets youmount DOS filesystems (FAT12, FAT16, and FAT32) under QNXNeutrino. This shared object is automatically loaded by the devb-*drivers when mounting a DOS FAT filesystem. If you want to readand write to a DOS floppy disk, mount it by typing something likethis:

mount -t dos /dev/fd0 /fd

For information about valid characters for filenames in a DOSfilesystem, see the MSDN Q100108/Q120138 articles. FAT 8.3 namesare the most limited; they’re uppercase letters, digits, and$%’- @{}˜#(). VFAT names relax it a bit and add the lowercase


CD-ROM filesystem

letters and [];,=+. Neutrino’s DOS filesystem silently converts FAT8.3 filenames to uppercase, to give the illusion that lowercase isallowed (non case-preserving).

For more information on the DOS filesystem manager, seefs-dos.so in the the Utilities Reference and Filesystems in theSystem Architecture guide.

CD-ROM filesystemThe CD-ROM filesystem provided in QNX Neutrino providestransparent access to CD-ROM media, so you can treat CD-ROMfilesystems as though they were POSIX filesystems. Thistransparency lets processes operate on CD-ROM files without anyspecial knowledge or work on their part.

The fs-cd.so shared object provides filesystem support for the ISO9660 standard as well as a number of extensions, including RockRidge (RRIP), Joliet (Microsoft), and multisession (Kodak Photo CD,enhanced audio). This shared object is automatically loaded by thedevb-* drivers when mounting an ISO-9660 filesystem.

The CD-ROM filesystem accepts any characters that it sees in afilename; it’s read-only, so it’s up to whatever prepares the CD imageto impose appropriate restrictions. Strict adherence to 9660 allowsonly 0-9A-Z , but Joliet and Rockridge are far more lenient.

If you’re interested in burning CDs, see the cdrecord software underQNX 6.x Fixes on http://developers.qnx.com/.

Linux Ext2 filesystemThe Ext2 filesystem provided in QNX Neutrino provides transparentaccess to Linux disk partitions. Not all Ext2 features are supported,including the following:

� file fragments (subblock allocation)

� large files greater than 2 G

� filetype extension


Flash filesystems

� compression

� B-tree directories.

The fs-ext2.so shared object provides filesystem support for Ext2.This shared object is automatically loaded by the devb-* driverswhen mounting an Ext2 filesystem.

CAUTION:

Although Ext2 is the main filesystem for Linux systems, we don’trecommend that you use fs-ext2.so as a replacement for theQNX 4 filesystem. Currently, we don’t support booting from Ext2partitions. Also, the Ext2 filesystem relies heavily on its filesystemchecker to maintain integrity; this and other support utilities (e.g.mke2fs) aren’t currently available for QNX Neutrino.

If an Ext2 filesystem isn’t unmounted properly, a filesystem checkeris usually responsible for cleaning up the next time the filesystem ismounted. Although the fs-ext2.so module is equipped to performa quick test, it automatically mounts the filesystem as read-only if itdetects any significant problems (which should be fixed using afilesystem checker).

This filesystem allows the same characters in a filename as the QNX 4filesystem; see “File names,” earlier in this chapter.

Flash filesystemsThe QNX Neutrino flash filesystem drivers implement aPOSIX-compatible filesystem on NOR flash memory devices. Theflash filesystem drivers are standalone executables that contain boththe flash filesystem code and the flash device code. There are versionsof the flash filesystem driver for different embedded systemshardware as well as PCMCIA memory cards.


CIFS filesystem

Flash filesystems don’t include . and .. entries for the current andparent directories.

�

The naming convention for the drivers is devf-system, where systemdescribes the embedded system. For example, the devf-800fadsdriver is for the 800FADS PowerPC evaluation board. For informationabout these drivers, see the devf-* entries in the Utilities Reference.

For more information on the way QNX Neutrino handles flashfilesystems, see:

� mkefs and flashctl in the Utilities Reference

� Filesystems in the System Architecture guide

� Building Embedded Systems.

CIFS filesystemCIFS, the Common Internet File System protocol, lets a clientworkstation perform transparent file access over a network to aWindows 98 or NT system or a UNIX system running an SMB server.It was formerly known as SMB or Server Message Block protocol,which was used to access resources in a controlled fashion over aLAN. File access calls from a client are converted to CIFS protocolrequests and are sent to the server over the network. The serverreceives the request, performs the actual filesystem operation, andthen sends a response back to the client. CIFS runs on top of TCP/IPand uses DNS.

The fs-cifs filesystem manager is a CIFS client operating overTCP/IP. To use it, you must have an SMB server and a valid login onthat server. The fs-cifs utility is primarily intended for use as aclient with Windows NT machines, although it also works with anySMB server, e.g. OS/2 Peer, LAN Manager, and SAMBA.

The fs-cifs filesystem manager requires a TCP/IP transport layer,such as the one provided by io-net with the full TCP/IP stack,npm-tcpip.so.


NFS filesystem

The CIFS filesystem manager doesn’t work properly with the tinyTCP/IP transport layer provided by npm-ttcpip.so.

�

For information about passwords — and some examples — seefs-cifs in the Utilities Reference.

If you want to start a CIFS filesystem when you boot your system, putthe appropriate command in/etc/host cfg/$HOSTNAME/rc.d/rc.local or/etc/rc.d/rc.local. For more information, see the description of/etc/rc.d/rc.sysinit in Starting Up Your System.

NFS filesystemThe Network File System (NFS) protocol is a TCP/IP application thatsupports networked filesystems. It provides transparent access toshared filesystems across networks.

NFS lets a client workstation operate on files that reside on a serveracross a variety of NFS-compliant operating systems. File accesscalls from a client are converted to NFS protocol (see RFC 1094 andRFC 1813) requests, and are sent to the server over the network. Theserver receives the request, performs the actual filesystem operation,and sends a response back to the client.

In essence, NFS lets you graft remote filesystems — or portions ofthem — onto your local namespace. Directories on the remotesystems appear as part of your local filesystem, and all the utilitiesyou use for listing and managing files (e.g. ls, cp, mv) operate on theremote files exactly as they do on your local files.

This filesystem allows the same characters in a filename as the QNX 4filesystem; see “File names,” earlier in this chapter.

Setting up NFSNFS consists of:


NFS filesystem

� a client that requests that a remote filesystem be grafted onto itslocal namespace

� a server that responds to client requests, enabling the clients toaccess filesystems as NFS mountpoints.

The procedures used in QNX for setting up clients and servers maydiffer from those used in other implementations. To set up clients andservers on a non-QNX system, see the vendor’s documentation andexamine the initialization scripts to see how the various programs arestarted on that system.

�

It’s actually the clients that do the work required to convert thegeneralized file access that servers provide into a file access methodthat’s useful to applications and users.

If you want to start an NFS filesystem when you boot your system,put the appropriate command in/etc/host cfg/$HOSTNAME/rc.d/rc.local or/etc/rc.d/rc.local. For more information, see the description of/etc/rc.d/rc.sysinit in Starting Up Your System.

NFS serverAn NFS server handles requests from NFS clients that want to accessfilesystems as NFS mountpoints. For the server to work, you need tostart the following programs:

Name: Purpose:

portmap Remote procedure call (RPC) portmapper

nfsd NFS server and mountd daemon

The portmap daemon maps RPC program/version numbers into TCPand UDP port numbers. Clients can make RPC calls only if portmapis running on the server.


NFS filesystem

The nfsd daemon reads the /etc/exports file, which lists thefilesystems that can be exported and optionally specifies which clientsthose filesystems can be exported to. If no client is specified, anyrequesting client is given access.

The nfsd daemon services both NFS mount requests and NFSrequests, as specified by the exports file. Upon startup, nfsd readsthe /etc/exports.hostname file (or, if this file doesn’t exist,/etc/exports) to determine which mountpoints to service.Changes made to this file don’t take affect until you restart nfsd.

NFS clientAn NFS client requests that a filesystem exported from an NFS serverbe grafted onto its local namespace. For the client to work, you needto start the version 2 or 3 of the NFS filesystem manager (fs-nfs2 orfs-nfs3) first. The file handle in version 2 is a fixed-size array of 32bytes. With version 3, it’s a variable-length array of 64 bytes.

The fs-nfs2 or fs-nfs3 filesystem manager is also the NFS 2 orNFS 3 client daemon operating over TCP/IP. To use it, you must havean NFS server and you must be running a TCP/IP transport layer suchas that provided by io-net with npm-ttcpip.so. It also needssocket.so and libc.so.

You can create NFS mountpoints with the mount command byspecifying nfs for the type and -o ver3 as an option. You must startfs-nfs3 or fs-nfs3 before creating mountpoints in this manner. Ifyou start fs-nfs2 or fs-nfs3 without any arguments, it runs in thebackground so you can use mount.

To make the request, the client uses the mount utility, as in thefollowing examples:

� Mount an NFS 2 client filesystem (fs-nfs2 must be runningfirst):mount -t nfs 10.1.0.22:/home /mnt/home

� Mount an NFS 3 client filesystem (fs-nfs3 must be runningfirst):


Package filesystem

mount -t nfs -o ver3 server node:/qnx bin /bin

In the first example, the client requests that the /home directory on anIP host be mounted onto the local namespace as /mnt/home. In thesecond example, NFS protocol version 3 is used for the networkfilesystem.

Here’s another example of a command line that starts and mounts theclient:

fs-nfs3 10.7.0.197:/home/bob /homedir

Although NFS 2 is older than POSIX, it was designed to emulateUNIX filesystem semantics and happens to be relatively close toPOSIX.

�

Package filesystemQNX Neutrino’s package filesystem is a virtual filesystem managerthat presents a customized view of a set of files and directories to aclient. The real files are present on some medium; the packagefilesystem presents a virtual view of selected files to the client.

The package filesystem is implemented as fs-pkg (see the UtilitiesReference). For an overview of the package filesystem, see “Virtualfilesystems” in the Filesystems chapter of the System Architectureguide.

Packages in their repositoriesThe purpose of the package filesystem is to manage packages in theirrepositories. It ensures that various nodes can pick and choose acustom set of files and directories they want to use. In essence, thepackage filesystem creates a virtual filesystem that redirects accessrequests to a “real” filesystem based on a set of user-selectedpackages. The contents of the various packages determine what thevirtual filesystem looks like.


Package filesystem

For example, consider a system that includes two packages, Core andUtil, where the Core Package contains:

� /pkgs/base/qnx/os/core1.0

� /pkgs/base/qnx/os/core1.0/etc/passwd

� /pkgs/base/qnx/os/core1.0/bin/true

� /pkgs/base/qnx/os/core1.0/x86/bin/cat

� /pkgs/base/qnx/os/core1.0/x86/bin/echo

and the Util package contains:

� /pkgs/base/qnx/util1.0/x86/bin/ls

The actual filesystem looks like this:

/pkgs/base/qnx

util1.0 core 2.1

x86

bin

ls

etc

passwd

bin

true

x86

bin

cat echo

Actual filesystem using the package filesystem.

but the virtual filesystem that the package filesystem presents to theuser looks like this:


Package filesystem

/

bin

truecat echo ls

etc

passwd

Virtual filesystem using the package filesystem.

When an open-style request comes to the virtual filesystem, a lookupis performed. The lookup determines if the file is indeed managed bythe package filesystem. If it is, then the system redirects the request tothe real location of the file inside the appropriate package. The reallocation could be on any filesystem (QNX 4, Linux, DOS), across thenetwork (via NFS, CIFS), or even cached locally (a shadowfilesystem). You should use the package filesystem manager, fs-pkg,to control which packages your node sees.

This style of redirection is similar to symbolic link. Once the file isopened, all I/O requests go directly to the file’s filesystem manager,bypassing the package filesystem. This way, the package filesystemdoesn’t interfere with read/write performance.

�

Your node creates a configuration file, typically called/etc/system/package or/etc/host cfg/$HOSTNAME/etc/system/packages, where theHOSTNAME environment variable specifies the name of the clientnode. This file tells the package filesystem which packages are to bepresented to the client node and where they should be placed.

To get information about a package, use the pkgctl utility.


Package filesystem

Spill directoryThe packages are read-only and immutable. The intent is to ensurethat you can install packages such that there’s never a collisionbetween files in the repositories. This lets multiple versions ofsoftware coexist on any one machine.

If you try to change a file that the package filesystem manages, the fileis transferred to the spill directory, which contains all localmodifications that have been made to used packages. This operationis (not surprisingly) known as spilling, and the files that you’vechanged are called spilled files.

If the package filesystem’s configuration file doesn’t specify alocation for the spill directory, the package filesystem operates as aread-only filesystem. The default spill directory is /var/pkg/spill.

As an example of spilling, consider the passwd file. After installingNeutrino, you should choose a password for the root user (it initiallyhas no password). When the passwd utility opens the passwd file forwriting, the package filesystem copies the file to the spill directory,From this point on, the package filesystem forwards all requests to thespill location rather than to the original file location in the package.


Package filesystem

/

etc

passwd

pkgs

core 2.1

etc

passwd

pkg

spill

etc

passwd

var

/

qnx

base

Virtual filesystem Actual filesystem

Has

passwdbeen

spilled?

No

Yes

Working with the spill directory.

If you want to restore a spilled file to its original version in thepackage, use the pkgctl command. For more information, see theUtilities Reference.

Underlying filesystemThere must be a filesystem underneath the redirection layer of thepackage filesystem.

If you want to copy a file to one of the virtual directories (e.g. /bin),then the package filesystem creates the appropriate structure on the


Package filesystem

underlying filesystem and then lets the original access request simplyfall through to the next server.

If there’s no underlying filesystem, then new files can’t be added tothe virtual filesystem without first generating a package for them.

Control filesThe package filesystem uses these control files:

Manifest files XML Files that you use to put together a packagefor distribution. The purpose of these files, whichlive at the root of every installed package, is todescribe which files are exported, the services thepackage provides, the dependencies of the package,etc. The packager utility builds these files.

For more information, see the Creating Packagesappendix of the Programmer’s Guide

Package-configuration file

An XML control file that’s used to configure thepackage filesystem itself. The installer utilities,qnxinstall and cl-installer, manipulate thisfile. Its default location is/etc/system/package/packages.

For more information, see Installing and RemovingSoftware.

PatchesThe package filesystem also supports patching. When patches areissued between releases, the files for the patch are placed into apackage as well. The patch package overrides existing files fromother packages without actually deleting them.


Inflator filesystem

Inflator filesystemQNX Neutrino provides an inflator virtual filesystem. It’s a resourcemanager that sits in front of other filesystems and inflates files thatwere previously deflated by the deflate utility.

You typically use inflator when the underlying filesystem is a flashfilesystem. Using it can almost double the effective size of the flashmemory.

For more information, see the Utilities Reference.

TroubleshootingHere are some problems that you might have with filesystems:

How can I make a specific flash partition read-only?

Unmount and remount the partition, like this:

flashctl -p raw mountpoint -umount -t flash -r raw mountpoint /mountpoint

where raw mountpoint indicates the partition (e.g./dev/fs0px).


Chapter 2

Transparent Networking via Qnet

In this chapter. . .What is Qnet? 31Qnet or TCP/IP? 31Conventions for naming nodes 33Software components for Qnet networking 34Starting Qnet 36Checking out the neighborhood 37Troubleshooting 38

Chapter 2 � Transparent Networking via Qnet 29

What is Qnet?

What is Qnet?A QNX native network is a group of interconnected workstationsrunning only the QNX Neutrino operating system. In this QNXnetwork, a program can transparently access any resource — whetherit’s a file, a device, or a process — on any other node (a computer or aworkstation) in the network. A program can also transparently run onother nodes.

The Qnet protocol provides transparent networking across a QNXnetwork; Qnet implements a local area network that’s optimized toprovide a fast, seamless interface between QNX workstations. AQNX network natively supports a variety of network hardware (e.g.Arcnet, Ethernet, Token Ring, FDDI). Whatever the type of hardware,a QNX network communicates via the Qnet protocol.

For QNX 4, the protocol used for QNX native networking is calledFLEET.

�

In essence, the Qnet protocol extends interprocess communication(IPC) transparently over a network of microkernels — takingadvantage of the message-passing paradigm of QNX Neutrino toimplement native networking. For example, in a client-serverscenario, several kernel calls are available — ConnectAttach(),MsgSend() — to get back a node descriptor necessary to build thenative network.

Network nodes generally have the prefix /net.�

For more details, see the Qnet Networking chapter of the SystemArchitecture guide. For information about programming with Qnet,see Qnet Networking chapter of the Programmer’s Guide.

Qnet or TCP/IP?


Qnet or TCP/IP?

Check the comparison of Qnet and TCP/IP.

When should you use Qnet, and when TCP/IP?

Qnet’s strengths:

� lightweight (small), native message passing IPC, good for smalltransactions on either reliable or unreliable networks

� provides low-level IPC; unaware of/agnostic to high-levelabstractions such as files

� transparent access to most QNX OS services because of ourmessage-passing architecture.

� suitable for Local Area Networks and IPC betweenloosely-coupled processors across a common backplane.

Qnet’s weaknesses:

� less efficient than some TCP/IP protocols for large transactionsand specialized functions (e.g. file transfer) for the same reason

� proprietary, not standard

� high-level operations (e.g. file I/O) won’t function betweenmachines of dissimilar endian-ness (Qnet doesn’t know abouthigh-level operations and can’t translate message content to suitdiffering endian-ness).

TCP/IP’s strengths:

� high throughput for large transactions

� supports specialized protocols that are tuned for performance inspecialized operations e.g. file transfer

� standards-based, facilitates communication between dissimilaroperating systems.

� suitable for both local- and wide-area networks.

32 Chapter 2 � Transparent Networking via Qnet

Conventions for naming nodes

Discuss pros/cons of: ftp, nfs, CIFS/SMB, rpc, http, socket vs. nativeIPC, etc.

For more information about TCP/IP, see TCP/IP Networking.

Conventions for naming nodesIn a network, an important challenge is to find the relevant details forthe remote node in a network-wide pathname space. In order toresolve names, the Qnet protocol follows certain conventions, asdescribed below:

node name A character string that identifies the node you’retalking to. Note that a node name can’t containslashes or dots. In the example below, we usedwintermute as one of our node names. Thedefault is the value of the CS HOSTNAMEconfiguration string.

node domain A character string that’s “tacked” onto the nodename by npm-qnet.so. Together, the node nameand node domain must form a string that’s uniquefor all nodes that are talking to each other. Thedefault is the value of the CS DOMAINconfiguration string.

fully qualified node name (FQNN)

The string formed by tacking the node name andnode domain together. For example, if the nodename is wintermute and the node domain nameis qnx.com, the resulting FQNN would be:wintermute.qnx.com.

network directory

A directory in the pathname space implemented bynpm-qnet.so. Each network directory — therecan be more than one on a node — has an


Software components for Qnet networking

associated node domain. The default is /net, asused in the examples in this chapter.

name resolution The process by which npm-qnet.so converts anFQNN to a list of destination addresses that thetransport layer knows how to get to.

name resolver A piece of code that implements one method ofconverting an FQNN to a list of destinationaddresses. Each network directory has a list ofname resolvers that are applied in turn to attemptto resolve the FQNN. The default is the NetworkDiscovery Protocol, ndp. See the UtilitiesReference for more information.

Software components for Qnet networkingYou need the following software entities (along with the hardware)for Qnet networking:

npm-qnet.so

Native network manager to implement Qnet protocols.

io-net Manager to provide support for dynamically loadednetworking modules.

Network drivers (devn-*)

Managers that form an interface with the hardware.


Software components for Qnet networking

io-net

Hardware

Client processes

npm-qnet.so

Network drivers

(devn-*.so)

Microkernel

Symbolic link

npm-qnet-compat.soor

npm-qnet-lwl4.so

Components of Qnet.

Neutrino includes two versions of the Qnet protocol stack:

npm-qnet-compat.so

The original stack.

npm-qnet-lwl4.so

The new, light-weight version, which provides faster speed andenhanced reliability. This version of the Qnet stack, however,


Starting Qnet

isn’t compatible with the earlier version with regard to packetand protocol format.

By default, npm-qnet.so is a symbolic link to the latest version ofthe Qnet protocol stack. To determine which version you’re using,type:

ls -l /lib/dll/npm-qnet.so

If any conflict arises, see “Troubleshooting,” later in this chapter.

Starting QnetYou can start Qnet by:

� creating a useqnet file, then rebooting

Or:

� explicitly starting the network manager, protocols, and drivers.

If you run Qnet, anyone else on your network who’s running Qnet canexamine your files and processes, if the permissions on them allow it.For more information, see “File ownership and permissions” inWorking with Files.

�

Creating useqnetTo start Qnet automatically when you boot your system, log in asroot and create an empty useqnet, like this:

touch /etc/system/config/useqnet

For more information about what happens when you boot yoursystem, see Starting Up Your System.


Checking out the neighborhood

Starting the network manager, protocols, and driversThe io-net manager is a process that assumes the central role to loada number of shared objects. In essence, it “controls” the operation ofthe entire protocol stack. In the case of native networking, the sharedobjects are npm-qnet.so, and networking drivers, such asdevn-ppc800-ads.so. The shared objects are arranged in ahierarchy, with the end user on the top, and hardware on the bottom.

You can start the io-net from the command line, telling it whichdrivers and protocols to load:

$ io-net -del900 -p npm-qnet &

This causes io-net to load the devn-el900.so Ethernet driver andthe Qnet protocol stack.

Alternatively, you can use the mount and umount commands to startand stop modules dynamically. The previous example could berewritten as:

$ io-net &$ mount -Tio-net devn-el900.so$ mount -Tio-net npm-qnet.so

To unload the driver or the Qnet protocol, you may use the followingcommand:

umount /dev/io-net/en0umount /dev/io-net/npm-qnet

Checking out the neighborhoodOnce you’ve started Qnet, the /net directory includes an entry for allother nodes on the network that are running Qnet. You can accessfiles and processes on other machines as if they were on your owncomputer (at least as far as the permissions allow).

For example, to display the contents of a file on another machine, youcan use less, specifying the path through /net:


Troubleshooting

less /net/alonzo/etc/TIMEZONE

To get system information about all of the remote nodes that are listedin /net, use pidin with the net argument:

$ pidin net

You can use pidin with the -n option to get information about theprocesses on another machine:

pidin -n alonzo | less

You can even run a process on another machine, using the -n optionto the on command:

on -n alonzo date

TroubleshootingAll the software components for the Qnet network should work inunison with the hardware to build a native network. If your Qnetnetwork isn’t working to your satisfaction, you may use several Qnetutilities to fetch diagnostic information to troubleshoot your hardwareas well as the network. Some of the typical questions are:

� Is Qnet running?

� Are io-net and the drivers running?

� Is the Qnet protocol stack or ethernet driver installed?

� Is the network card functional?

� How do I get diagnostic information?

� Is the Qnet version correct?

� Is the hostname unique?


Troubleshooting

Is Qnet running?Qnet creates the /net directory. Use the following command to makesure that it exists:

$ ls /net

If you don’t see any directory, Qnet isn’t running. Ideally, thedirectory should include at least an entry with the name of yourmachine (i.e. the output of the hostname command). If you’re usingthe Ethernet binding, all other reachable machines are also displayed.For example:

joseph/ eileen/

Are io-net and the drivers running?As mentioned before, io-net is the framework used to connectdrivers and protocols. In order to troubleshoot this, use the followingpidin command:

$ pidin -P io-net mem

Look for the Qnet shared object in the output:

pid tid name prio STATE code data stack

86034 1 sbin/io-net 10o SIGWAITINFO 56K 684K 8192(516K)*86034 2 sbin/io-net 10o RECEIVE 56K 684K 4096(68K)86034 3 sbin/io-net 10o RECEIVE 56K 684K 4096(68K)86034 4 sbin/io-net 10o RECEIVE 56K 684K 4096(68K)86034 5 sbin/io-net 20o RECEIVE 56K 684K 4096(132K)86034 6 sbin/io-net 10o RECEIVE 56K 684K 4096(68K)86034 7 sbin/io-net 21r RECEIVE 56K 684K 4096(132K)86034 8 sbin/io-net 10r RECEIVE 56K 684K 4096(132K)86034 9 sbin/io-net 10o RECEIVE 56K 684K 4096(132K)86034 10 sbin/io-net 10o RECEIVE 56K 684K 4096(132K)

ldqnx.so.2 @b0300000 312K 16Knpm-tcpip.so @b8200000 592K 144Kdevn-el900.so @b82b8000 56K 4096devn-epic.so @b82c7000 44K 4096

npm-qnet-lwl4.so @b82d3000 132K 16K

If the output includes an npm-qnet shared object, Qnet is running.


Troubleshooting

Is the Qnet protocol stack or ethernet driver installed?In order to ascertain the above, use the following command:

$ ls /dev/io-net

Ideally, you should see the following output:

en0 ip0 ip en ipv6 en qnet en

The en0 entry represents the first (and only) Ethernet driver, andqnet en represents the Qnet protocol stack.

Is the network card functional?To determine whether or not the network card is functional, i.e.transmitting and receiving packets, use the nicinfo command. Ifyou’re logged in as root, your PATH includes the directory thatcontains the nicinfo executable; if you’re logged in as another user,you have to specify the full path:

$ /usr/sbin/nicinfo

Now figure out the diagnostic information from the following output:

3COM (90xC) 10BASE-T/100BASE-TX Ethernet ControllerPhysical Node ID ................. 000103 E8433FCurrent Physical Node ID ......... 000103 E8433FMedia Rate ....................... 10.00 Mb/s half-duplex UTPMTU .............................. 1514Lan .............................. 0I/O Port Range ................... 0xA800 -> 0xA87FHardware Interrupt ............... 0x7Promiscuous ...................... DisabledMulticast ........................ Enabled

Total Packets Txd OK ............. 1283237Total Packets Txd Bad ............ 9Total Packets Rxd OK ............. 7923747Total Rx Errors .................. 0

Total Bytes Txd .................. 82284687Total Bytes Rxd .................. 1612645356


Troubleshooting

Tx Collision Errors .............. 34380Tx Collisions Errors (aborted) ... 0Carrier Sense Lost on Tx ......... 0FIFO Underruns During Tx ......... 0Tx deferred ...................... 83301Out of Window Collisions ......... 0FIFO Overruns During Rx .......... 0Alignment errors ................. 0CRC errors ....................... 0

You should take special note of the Total Packets Txd OK andTotal Packets Rxd OK counters. If they’re zero, the driver mightnot be working, or the network might not be connected. Verify thatthe Media Rate has been auto-detected correctly by the driver.

How do I get diagnostic information?You can find diagnostic information in /proc/qnetstats. If thisfile doesn’t exist, Qnet isn’t running.

The qnetstats file contains a lot of diagnostic information that’smeaningful to a Qnet developer, but not to you. However, you can usegrep to extract certain fields:

$ cat /proc/qnetstats | grep "compiled"**** Qnet compiled on Jun 25 2003 at 17:14:27 running on qnet02

or:

$ cat /proc/qnetstats | grep -e "ok" -e "bad"txd ok 19415966txd bad 31rxd ok 10254788rxd bad dr 0rxd bad L4 0

If you need help getting Qnet running, our Technical Supportdepartment might ask you for a copy of this file.


Troubleshooting

Is the Qnet version correct?Since Neutrino includes two versions of Qnet stacks that areincompatible in regard to packet and protocol format, a conflict couldarise, and native networking might not work. If this happens, makesure that npm-qnet.so is a symbolic link to the correct version ofthe Qnet protocol stack.

Alternately, you may also use the ping command:

$ ping

to verify if all other things (such as network cards, TCP protocol) areworking. If ping works, you may safely infer that the only problemlies with the versions of the Qnet.

Is the host name unique?Use the hostname command to see the host name:

$ hostname

This hostname must be unique for Qnet to work.


Chapter 3

TCP/IP Networking

In this chapter. . .Overview of TCP/IP 45Software components for TCP/IP networking 48Choosing the right stack configuration 49Running the Internet daemons 52Running multiple instances of the TCP/IP stack 54Using the Point-to-Point Protocol over Ethernet (PPPoE) 55Using the SRI SNMP suite for QNX Neutrino 57Troubleshooting 57

Chapter 3 � TCP/IP Networking 43

Overview of TCP/IP

Overview of TCP/IPThe term TCP/IP implies two distinct protocols: TCP and IP. Sincethese protocols have been used so commonly together, TCP/IP hasbecome a standard terminology in today’s Internet. Essentially,TCP/IP refers to network communications where the TCP transport isused to deliver data across IP networks.

This chapter provides information on setting up TCP/IP networkingon a QNX Neutrino network. It also provides troubleshooting andother relevant details from a system-administration point of view. AQNX Neutrino-based TCP/IP network can access resources locatedon any other system that supports TCP/IP. For a discussion of QNXNeutrino TCP/IP specifics, see TCP/IP Networking in the SystemArchitecture guide.

TCP/IP is a different network model from that of a Qnet nativenetwork in the sense that it isn’t limited to LANs. A TCP/IP host orworkstation can send information across multiple intermediate hopsto reach its destination. These hops can span many physical networks,over a wide or local area.

Let’s start with some terminology.

Clients and serversThere are two types of TCP/IP hosts: clients and servers. A clientrequests TCP/IP service; a server provides it. In planning yournetwork, you must decide which hosts will be servers and which willbe clients.

For example, if you want to telnet from a machine, you need to setit up as a client; if you want to telnet to a machine, it has to be aserver.

Hosts and gatewaysIn TCP/IP terminology, we always refer to network-accessiblecomputers as hosts or gateways.


Overview of TCP/IP

Host A node running TCP/IP that doesn’t forward IP packetsto other TCP/IP networks; a host usually has a single IP(Internet Protocol) address associated with it.

Gateway A node running TCP/IP that forwards IP packets toother TCP/IP networks entries in the/etc/resolv.conf file.

In order to use TCP/IP, you need an IP address, and, to find a node’sIP address, you need a nameserver.

�

NameserversA nameserver is a database that contains the names and IP addressesof hosts.

You normally access a TCP/IP or Internet host with a text name (e.g.www.qnx.com) rather than an IP address (209.226.137.1). Tomake this possible, you must have one of:

� an entry for the host you want in the /etc/hosts file

Or:

� a nameserver entry in the configuration string CS RESOLVEobtained from a configuration file (default /etc/net.cfg)

Or:

� a nameserver entry in the /etc/resolv.conf file.

The simplest way to map between alphanumeric names (e.g.www.qnx.com) and IP addresses is via a table kept in the/etc/hosts file. This works well for small to medium networks. Ifyou have something a bit more complicated than a small internalnetwork with a few hosts, you need a nameserver (e.g. for an ISPconnection to the Internet).

If someone attempts to connect to a TCP/IP host using a name, thenameserver is asked for the corresponding IP address, and the

46 Chapter 3 � TCP/IP Networking

Overview of TCP/IP

connection is then made to that IP address. If you’re using phlip, thePhoton TCP/IP and dialup configuration tool, to configure thenetwork and specify nameservers, they’re loaded in the configurationstring CS RESOLVE. This string, if it exists, is always searchedinstead of /etc/resolv.conf. If you aren’t using phlip, you canadd your nameserver entries in /etc/resolv.conf. For example:

nameserver 10.0.0.2 nameserver 10.0.0.3

For more information on finding TCP/IP host names and nameservers,see /etc/hosts and /etc/resolv.conf in the Utilities Reference.

RoutingRouting determines how to get a packet to its intended destination.The general categories of routing are:

Minimal routing

If you’re isolated on your own network (on a singlepiece of wire), it’s unlikely that you’ll need to doanything to route packets.

Static routing If you’re on a network with a small (and static overtime) number of gateways, then you can use theroute command to manually manipulate theTCP/IP routing tables and leave them that way.This is a very common configuration.

Dynamic routing

If you’re on a network with more than one possibleroute to the same destination on your network, youmight need to use dynamic routing. This relies onrouting protocols to distribute information about thechanging state of the network. If you need to reactto these changes, run routed.

There’s often confusion between routing and routing protocols.Routing is done by TCP/IP via routing tables; routing protocols allowthose tables to change.


Software components for TCP/IP networking

Software components for TCP/IP networkingTo use TCP/IP, you need:

npm-tcpip.so or npm-ttcpip.so

Shared objects that implement the full and tiny TCP/IPstacks.

io-net Manager that provides support for dynamically loadednetworking modules.

Network drivers (devn-*)

Managers that form an interface with the hardware.


Choosing the right stack configuration

io-net

Hardware

Client processes

npm-tcpip.so or npm-ttcpip.so

Network drivers

(devn-*.so)

Components of TCP/IP

Choosing the right stack configurationQNX Neutrino supports TCP/IP with two different stacks:

� a tiny stack (npm-ttcpip.so)

� a full BSD 4.4 TCP/IP stack (npm-tcpip.so).

The tiny stack is meant for resource-constrained applications where itisn’t necessary to have all TCP/IP services present; for a list of theservices not covered in the tiny stack, see the limitations listed in theUtilities Reference.



The way that you set configuration parameters depends on whichstack you use:

� If you’re using the tiny stack, use command-line options.

� If you’re using the full stack, use the ifconfig and route

utilities.

These methods are described below. For either stack, if you’re usingthe Dynamic Host Configuration Protocol (DHCP), you can usedhcp.client to set the configuration parameters.

Tiny stack (npm-ttcpip.so)Use the tiny stack when you need to conserve resources. It containsmany, but not all, of the functions found in the full TCP/IP stack; seenpm-ttcpip.so in the Utilities Reference for a list of its limitations.

When you start the tiny stack, use the command-line options to set theconfiguration parameters. For example:

io-net -dne2000 -pttcpip if=en0:10.100,default=10.1

To see how you’ve configured your system or to view the currentnetwork connections when using the tiny stack, read the/proc/ipstats file, like this:

cat /proc/ipstats

You’ll see something like this:

Ttcpip Jun 15 2000 22:36:01

verbosity level 0ip checksum errors: 0udp checksum errors: 0tcp checksum errors: 0

packets sent: 0packets received: 0

en0 : addr 10.0.0.100 netmask 255.0.0.0 downlo0 : addr 127.0.0.1 netmask 255.0.0.0 up



DST: 10.0.0.0 NETMASK: 255.0.0.0 GATEWAY: en0DST: 127.0.0.0 NETMASK: 255.0.0.0 GATEWAY: lo0DST: 0.0.0.0 NETMASK: 0.0.0.0 GATEWAY: 10.0.0.1

Here you can see that the interface has been configured to10.0.0.100 and the default route has been set to 10.0.0.1.

Full TCP/IP stack (npm-tcpip.so)The full TCP/IP stack, npm-tcpip.so, is based on the BSD 4.4TCP/IP stack, and it supports similar features. If you aren’t usingphlip (the Photon TCP/IP and dialup configuration tool) to configurethe full stack, you have to use the ifconfig and route utilities asdescribed below — you can’t use command-line options as you wouldfor the tiny stack.

To start the full stack, load the TCP/IP shared object into io-net.For example:

io-net -dne2000 -ptcpip

To configure an interface with an IP address, you must use theifconfig utility. To configure your network interface with an IPaddress of 10.0.0.100, you would use the following command:

ifconfig en0 10.0.0.100

If you also want to specify your gateway, use the route command:

route add default 10.0.0.1

This configures the gateway host as 10.0.0.1.

If you then want to view your network configuration, use thenetstat command (netstat -in displays information about thenetwork interfaces):

Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Colllo0 32976 <Link> 0 0 0 0 0lo0 32976 127 127.0.0.1 0 0 0 0 0en0 1500 <Link> 00:50:da:c8:61:92 21 0 2 0 0en0 1500 10 10.0.0.100 21 0 2 0 0


Running the Internet daemons

To display information about the routing table in the full stack, usenetstat -rn; the resulting display looks like this:

Routing tables

Internet:Destination Gateway Flags Refs Use Mtu Interfacedefault 10.0.0.1 UGS 0 0 - en010 10.0.0.100 U 1 0 - en010.0.0.100 10.0.0.100 UH 0 0 - lo0127.0.0.1 127.0.0.1 UH 0 0 - lo0

The table shows that the default route to the gateway was configured(10.0.0.1).

Running the Internet daemonsIf a host is a server, it invokes the appropriate daemon to satisfy aclient’s requests. A TCP/IP server typically runs the inetd daemon,also known as the Internet super-server. You can start inetd in yourmachine’s rc.local file; see the description of/etc/rc.d/rc.sysinit in Starting Up Your System.

CAUTION:

Running inetd lets outside users try to connect to your machine andthus is a potential security problem.

The inetd daemon listens for connections on some well-known portsin the TCP/IP network. On receiving a request, it runs thecorresponding server daemon. For example, if a client requests aremote login by invoking rlogin, then inetd starts rlogind(remote login daemon) to satisfy the request. In most instances,responses to client requests are handled this way.

You use the super-server configuration file /etc/inetd.conf tospecify the daemons that inetd can start. As shipped in the QNXNeutrino distribution, the file describes all currently shipped QNXNeutrino TCP/IP daemons and some nonstandard pidin services.Unless you want to add or remove daemon definitions, you don’t need


Running the Internet daemons

to modify this file. When it starts, inetd reads its configurationinformation from this configuration file. It includes these commonlyused daemons:

The daemon for: Is:

File transfer ftpd

Remote login rlogind

Remote file transfer rftp

Remote shell rshd

Remote terminal session telnetd

DARPA trivial file transfer tftpd

� Remember that you shouldn’t manually start the daemon processeslisted in this file; they expect to be started by inetd.

� Running rshd can open up your machine to the world. If you usethe /etc/hosts.equiv or ˜/.rhosts files (or both) to identifytrusted users, be very careful.

�

You may also find other resident daemons which can runindependently of inetd — see the Utilities Reference fordescriptions:

The daemon for: Is:

Implementing Internet boot protocol bootpd

Managing line printers (see Printing) lpd

Mapping Internet domain names named

Managing network routing tables routed

continued. . .


Running multiple instances of the TCP/IP stack

The daemon for: Is:

Maintaining system status database rwhod

Tiny HTTP web server slinger

SNMP agent snmpd

NFS server nfsd

These daemons listen on their own TCP ports and manage their owntransactions. They’re usually started when the computer boots andthen run continuously, although to conserve system resources, youcan have inetd start bootpd only when a boot request arrives.

Running multiple instances of the TCP/IPstackIn some situations, you may need to run multiple instances of theTCP/IP stack. In order to do that, follow the steps given below:

The assumption is that you have two same type of Network Interfacecontroller (NIC) cards.

�

1 Start the first instance of the TCP/IP stack by invoking io-netas follows:io-net -del900 pci=0x0 -ptcpip

2 Start the second instance of the TCP/IP stack by invokingio-net as follows:io-net -i1 -del900 pci=0x1 -ptcpip prefix=/sock2

You can get the PCI index of your NIC cards by using the pci-vvv command. If you’re using different types of NIC cards,you don’t have to specify the PCI index.

The -i option in the second instance of TCP/IP tells io-net toregister itself as /dev/io-net1. The prefix option to


Using the Point-to-Point Protocol over Ethernet (PPPoE)

npm-tcpip.so causes the second stack to be registered as/sock2/dev/socket instead of the default, /dev/socket. TCP/IPapplications that wish to use the second stack must specify theenvironment variable SOCK. For example:

SOCK=/sock2 telnet 10.59

or:

SOCK=/sock2 netstat -in

or:

SOCK=/sock2 ifconfig en0 192.168.2.10

If you don’t specify SOCK, the command uses the first TCP/IP stack.

Using the Point-to-Point Protocol overEthernet (PPPoE)PPPoE stands for Point-to-Point Protocol over Ethernet. It’s a methodof encapsulating your data for transmission over a bridged Ethernettopology.

PPPoE is a specification for connecting users on an Ethernet networkto the Internet through a broadband connection, such as a single DSLline, wireless device, or cable modem. Using PPPoE and a broadbandmodem, LAN users can gain individual authenticated access tohigh-speed data networks.

By combining Ethernet and the Point-to-Point Protocol (PPP), PPPoEprovides an efficient way to create a separate connection to a remoteserver for each user. Access, billing, and choice of service aremanaged on a per-user basis, rather than a per-site basis. It has theadvantage that neither the telephone company nor the Internet serviceprovider (ISP) needs to provide any special support.

Unlike dialup connections, DSL and cable modem connections arealways on. Since a number of different users are sharing the same


Using the Point-to-Point Protocol over Ethernet (PPPoE)

physical connection to the remote service provider, a way is needed tokeep track of which user traffic should go to where, and which usershould be billed. PPPoE lets each user-remote site session to learneach other’s network addresses (during an initial exchange calleddiscovery). Once a session is established between an individual userand the remote site (for example, an Internet service provider), thesession can be monitored for billing purposes. Many apartmenthouses, hotels, and corporations are now providing shared Internetaccess over DSL lines using Ethernet and PPPoE.

A PPPoE connection is composed of a client and a server. Both theclient and server work over any Ethernet-like interface. It’s used tohand out IP addresses to the clients, based on the user (andworkstation if desired), as opposed to workstation-onlyauthentication. The PPPoE server creates a point-to-point connectionfor each client.

Establishing a PPPoE session

Use the pppoed daemon to negotiate a PPPoE session. Thenpm-pppoe.so shared object provides PPP-to-Ethernet services.Start io-net with this shared object. For example:

io-net -del900 -pttcpip -ppppmgr -ppppoe

Then, make a session to any server using file /etc/ppp/pppoe-upto start pppd:

pppoed

Make a session to the server with name of PPPOE GATEWAY:

pppoed name=PPPOE GATEWAY

Once the PPPOE session is established, pppoed uses pppd to create apoint-to-point connection over the PPPOE session. The pppd daemongets a local TCP/IP configuration from the server (ISP).


Using the SRI SNMP suite for QNX Neutrino

Starting a point-to-point connection over PPPoE session

The pppoed daemon uses pppd to establish TCP/IP serialconnections using the point-to-point protocol (PPP). The protocolconsists of:

� a method for encapsulating datagrams over serial links

� an extensible Link Control Protocol (LCP)

� a family of Network Control Protocols (NCP) for establishing andconfiguring different network-layer protocols.

The encapsulation scheme is provided by driver code in the kernel.The pppd utility provides the basic LCP, authentication support, andan NCP for establishing and configuring the Internet Protocol (IP)called the IP Control Protocol (IPCP).

Using the SRI SNMP suite for QNX NeutrinoThe Simple Network Management Protocol (SNMP) is anapplication-layer protocol that facilitates the exchange of managementinformation between network devices. It uses the TransmissionControl Protocol/Internet Protocol (TCP/IP) protocol suite. SNMPenables network administrators to manage network performance, findand solve network problems, and plan for network growth.

The SRI SNMP Suite for QNX Neutrino consists primarily of ports ofthe EMANATE and EMANATE/Lite technologies developed bySNMP Research International (SRI). EMANATE/Lite is a staticallyextensible agent; the EMANATE agent can be extended dynamically.Both agents support SNMP V1, V2, and V3, and include developmentkits for developers to extend the agents.

TroubleshootingIf you’re having trouble with your TCP/IP network (i.e. you can’tsend packets over the network), you need to use several utilities fortroubleshooting. These utilities query hosts, servers, and the gateways


Troubleshooting

to fetch diagnostic information to locate faults. Some of the typicalqueries are:

� Are io-net and the drivers running?

� Is TCP/IP protocol stack or ethernet driver installed?

� What is the nameserver information?

� How do I map host names to IP addresses?

� How do I get the network status?

� How do I make sure I’m connected to other hosts?

� How do I display information about an interface controller?

Are io-net and the drivers running?As mentioned before, io-net is the framework used to connectdrivers and protocols. In order to troubleshoot this, use the pidincommand:

$ pidin -P io-net mem

Look for the TCP/IP shared object in the output:

pid tid name prio STATE code data stack

77839 1 sbin/io-net 10o SIGWAITINFO 56K 384K 8192(516K)*

77839 2 sbin/io-net 10o RECEIVE 56K 384K 4096(68K)77839 3 sbin/io-net 10o RECEIVE 56K 384K 4096(68K)

77839 4 sbin/io-net 10o RECEIVE 56K 384K 4096(68K)77839 5 sbin/io-net 10o RECEIVE 56K 384K 4096(68K)

77839 6 sbin/io-net 20o RECEIVE 56K 384K 4096(132K)

77839 7 sbin/io-net 21r RECEIVE 56K 384K 4096(132K)ldqnx.so.2 @b0300000 300K 16K

npm-tcpip.so @b8200000 584K 140K

devn-el900.so @b82b5000 56K 8192

Look for the npm-tcpip.so shared object at the end — this is good!


Troubleshooting

If you see npm-ttcpip.so instead of npm-tcpip.so in the aboveoutput, you’re using the tiny TCP/IP stack.

�

Is TCP/IP protocol stack or ethernet driver installed?In order to ascertain the above, use the following command:

$ ls /dev/io-net

Ideally, you should see the following output:

en0 ip0 ip en ipv6 en

The en0 entry represents the first (and only) ethernet driver; ip en

and ipv6 en represent the TCP/IP protocol stack, which was startedby mounting npm-tcpip.so, which is actually a shared object thatio-net loads.

What is the nameserver information?Use the following command to get the nameserver information:

getconf CS RESOLVE

If you aren’t using the configuration string, type:

cat /etc/resolv.conf

How do I map host names to IP addresses?The /etc/hosts file contains information regarding the known hostson the network. For each host, a single line should be present with thefollowing information:

internet address official host name aliases

Display this file by using the following command:

cat /etc/hosts


Troubleshooting

How do I get the network status?If you’re using the full TCP/IP stack, use the following netstatcommands to get the network status:

netstat -in

List the interfaces, including the MAC and IP addresses thatthey’ve been configured with.

netstat -rn

Display the network routing tables that determine how the stackcan reach another host. If there’s no route to another host, youget a “no route to host” error.

netstat -an

List information about TCP/IP connections to or from yoursystem. This includes the state of the connections or the amountof data pending on the connections. It also provides the IPaddresses and ports of the local and remote ends of theconnections.

For the tiny TCP/IP stack, you have to use the following command asit doesn’t support netstat:

$ cat /proc/ipstats

For more information about netstat, see the Utilities Reference.

How do I make sure I’m connected to other hosts?Use the ping utility to determine if you’re connected to other hosts.For example:

ping isp.com

On success, ping displays something like this:


Troubleshooting

PING isp.com (10.0.0.1): 56 data bytes64 bytes from 10.0.0.1: icmp seq=0 ttl=255 time=0 ms64 bytes from 10.0.0.1: icmp seq=1 ttl=255 time=0 ms64 bytes from 10.0.0.1: icmp seq=2 ttl=255 time=0 ms64 bytes from 10.0.0.1: icmp seq=3 ttl=255 time=0 ms64 bytes from 10.0.0.1: icmp seq=4 ttl=255 time=0 ms64 bytes from 10.0.0.1: icmp seq=5 ttl=255 time=0 ms64 bytes from 10.0.0.1: icmp seq=6 ttl=255 time=0 ms

This report continues until you terminate ping, for example, bypressing Ctrl – C.

How do I display information about an interfacecontroller?Use the nicinfo command:

/usr/sbin/nicinfo device

If you aren’t logged in as root, you have to specify the full path tonicinfo.

�

This utility displays information about the given network interfaceconnection, or /dev/io-net/en0 if you don’t specify one. Theinformation includes the number of packets transmitted and received,collisions, and other errors, as follows:

3COM (90xC) 10BASE-T/100BASE-TX Ethernet ControllerPhysical Node ID ................. 000103 E8433FCurrent Physical Node ID ......... 000103 E8433FMedia Rate ....................... 10.00 Mb/s half-duplex UTPMTU .............................. 1514Lan .............................. 0I/O Port Range ................... 0xA800 -> 0xA87FHardware Interrupt ............... 0x7Promiscuous ...................... DisabledMulticast ........................ Enabled

Total Packets Txd OK ............. 1585370Total Packets Txd Bad ............ 9Total Packets Rxd OK ............. 11492102Total Rx Errors .................. 0


Troubleshooting

Total Bytes Txd .................. 102023380Total Bytes Rxd .................. 2252658488

Tx Collision Errors .............. 39598Tx Collisions Errors (aborted) ... 0Carrier Sense Lost on Tx ......... 0FIFO Underruns During Tx ......... 0Tx deferred ...................... 99673Out of Window Collisions ......... 0FIFO Overruns During Rx .......... 0Alignment errors ................. 0CRC errors ....................... 0.


Appendix A

Examples

In this appendix. . .Buildfile for an NFS-mounting host 65qnxbasedma.build 68.profile 70.kshrc 70Configuration files for spooler 71Configuration files for setting up a firewall 76

Appendix: A � Examples 63

Buildfile for an NFS-mounting host

This appendix includes examples of the following:

� Buildfile for an NFS-mounting host

� qnxbasedma.build

� .profile

� .kshrc

� Configuration files for spooler

� Configuration files for setting up a firewall

Buildfile for an NFS-mounting hostHere’s a sample buildfile for an NFS-mounting development host.

In a real buildfile, you can’t use a backslash (\) to break a long lineinto shorter pieces, but we’ve done that here, just to make the buildfileeasier to read.

�

###########################################################################

#

# On-board devices# ----------------

#

# device: Raven PCI# pci: pci-raven

#

# device: VT82C586C Super I/O# serial: devc-ser8250 -c1846200 0xfe0003f8,104 0xfe0002f8,103

# floppy: no driver# keyboard: ?

# mouse: ?

# parallel: ?#

# device: DEC21140

# network: io-net -dtulip irq=2,media=9 -pnraw -pttcpip if=en0:1.2.3.4#

# device: VT82C586B

# disk: devb-eide eide ioport=0x8ffffff0:0x8fffffe8,irq=114#

###########################################################################

[image=0x1f0000][virtual=ppcbe/prepboot] .bootstrap = {

startup-mcp750

PATH=/proc/boot:/bin:/usr/bin:/mnt/bin:/mnt/usr/bin:/mnt/sbin:/mnt/usr/sbin \LD LIBRARY PATH=/proc/boot:/lib:/usr/lib:/lib/dll procnto-600-instr -vv



}

[+script] .script = {

procmgr symlink ../../proc/boot/libc.so.2 /usr/lib/ldqnx.so.2

devc-ser8250 -e -c1846200 -b9600 0x800003f8,104 0x800002f8,103 &

reopendisplay msg Starting QNX 6.2.1 on MCP750

slogger &

# Start the pci serverpci-raven &

# Start the network driver - substitute your IP addressio-net -dtulip irq=2,media=9 -ptcpip

# io-net -dtulip irq=2,media=9 -pnraw -pttcpip if=ndi0:1.2.3.4

# These env variables inherited by all the programs which follow

SYSNAME=nto

TERM=qansiLD LIBRARY PATH=/proc/boot:/lib:/usr/lib:/lib/dll

[+session] PATH=/bin:/proc/boot:/mnt/bin:/mnt/sbin:/mnt/usr/bin:/mnt/usr/sbin \sh /proc/boot/mount.sh

display msg "Starting Shell"[+session] sh &

}

[type=link] /dev/console=/dev/ser1

[type=link] /tmp=/dev/shmem

[type=link] /etc=/mnt/etc[type=link] /usr/bin=/mnt/usr/bin

[type=link] /lib=/mnt/lib

[type=link] /usr/lib=/mnt/usr/lib[type=link] /usr/photon=/mnt/usr/photon

[type=link] /bin=/mnt/bin

[type=link] /sbin=/mnt/sbin[type=link] /usr/sbin=/mnt/usr/sbin

libc.solibm.so

libsocket.so.2npm-tcpip.so

devn-tulip.so

[data=c]

slogger

sloginfodevc-ser8250

io-net

ifconfigpci-raven

pidin

fs-nfs3shutdown

pci

#unamesh=ksh

ls

66 Appendix: A � Examples


#sleep

# Here’s the script that does the NFS mount - prompting for IP addresses etc.

#Set the defaults for your usual setup, and/or modify the file not to ask...

[perms=755] mount.sh = {

#!/bin/sh

# Change these defaults if you wish

# IP address of NFS server to mount from

SERVER IP="192.168.56.108"

# Local IP address

LOCAL IP="192.168.56.118"

# Remote server mount point

REMOTE MOUNT="/ppcbe"

# local mount point

LOCAL MOUNT="/mnt"

# Ethernet device to use

EN DEVICE=en0

echo "Please enter the local IP address to use [$LOCAL IP]"read lip

if test "X$lip" == "X";

thenlip=$LOCAL IP

echo "Using default: $lip"

elseecho "New address: $lip"

fi

echo

echo "Please enter the server IP address to use [$SERVER IP]"

read sipif test "X$sip" == "X";

then

sip=$SERVER IPecho "Using default: $sip"

elseecho "New address: $sip"

fi

echo

echo "Please enter the full path of the directory to mount from the NFS server"

echo "[$REMOTE MOUNT]"read ndir

if test "X$ndir" == "X";

thenndir=$REMOTE MOUNT

echo "Using default: $ndir"

elseecho "New address: $ndir"

fi

echo "Initializing ethernet port"


qnxbasedma.build

ifconfig $EN DEVICE $lip

echo "Starting fs-nfs3 client"

fs-nfs3 $sip:$ndir $LOCAL MOUNT

echo "Mounting Done"

}

qnxbasedma.buildHere’s the buildfile for .boot on an x86 platform,qnxbasedma.build:

In a real buildfile, you can’t use a backslash (\) to break a long lineinto shorter pieces, but we’ve done that here, just to make the buildfileeasier to read.

�

## The build file for QNX Neutrino booting on a PC#[virtual=x86,bios +compress] boot = {

# Reserve 64k of video memory to handle multiple video cardsstartup-bios -s64k

# PATH is the *safe* path for executables# (confstr( CS PATH...))# LD LIBRARY PATH is the *safe* path for libraries# (confstr( CS LIBPATH)) i.e. This is the path searched# for libs in setuid/setgid executables.PATH=/proc/boot:/bin:/usr/bin LD LIBRARY PATH=/proc/boot:\

/lib:/usr/lib:/lib/dll procnto}

[+script] startup-script = {# To save memory make everyone use the libc in the boot# image! For speed (fewer symbolic lookups), point to# libc.so.2 instead of libc.soprocmgr symlink ../../proc/boot/libc.so.2 /usr/lib/ldqnx.so.2

# Default user programs to priority 10, other scheduler (pri=10o)# Tell "diskboot" this is a hard disk boot (-b1)# Tell "diskboot" to use DMA on IDE drives (-D1)# Start 4 text consoles buy passing "-n4" to "devc-con" (-o)# By adding "-e" Linux ext2 filesystem will be mounted as well.[pri=10o] PATH=/proc/boot diskboot -b1 -D1 -odevc-con,-n4


qnxbasedma.build

}

# Include the current "libc.so". It will be created as a real# file using its internal "SONAME", with "libc.so" being a# symlink to it. The symlink will point to the last "libc.so.*"# so if an earlier libc is needed (e.g. libc.so.1), add it# before the this line.libc.so

# Include all tie files for the default filesystemslibcam.soio-blk.socam-disk.sofs-qnx4.sofs-dos.sofs-ext2.socam-cdrom.sofs-cd.so

# These programs only need to be run once from the boot image.# "data=uip" will waste less memory as the ram from the boot# image will be used directly without making a copy of the data# (i.e. as the default "data=cpy" does). When they have been# run once, they will be unlinked from /proc/boot.[data=uip]seedrespci-biosdevb-eidedevb-amddevb-aha2devb-aha4devb-aha7devb-aha8devb-ncr8diskbootsloggerfesh

# These files will be unlinked after the system has started# to release the memory back to the system. They are only# needed during boot. If needed later on, they will be loaded# from the boot device.unlink list={/proc/boot/devb-*}

For more information about buildfiles (including some othersamples), see Building Embedded Systems.


.profile

.profileWhen you create a new user account, the user’s initial .profile iscopied from /etc/skel/.profile (see Managing User Accounts).Here’s what’s in that file:

# default .profileif test "$(tty)" != "not a tty"; thenecho ’edit the file .profile if you want to change your environment.’echo ’To start the Photon windowing environment, type "ph".’fi

This profile runs the tty utility to get the name of the terminal that’sopen as standard input. If there is a terminal, .profile simplydisplays a couple of helpful hints.

You might want to set some environment variables:

EDITOR The path to your favorite editor (the default is vi).

ENV The name of the profile that ksh should run wheneveryou start a shell.

The code for these changes could look like this:

export EDITOR=/usr/local/bin/jedexport ENV=$HOME/.kshrc

.kshrcHere’s an example of a profile that ksh runs if you set the ENVenvironment variable as described above for .profile:

alias rm="rm -i"alias ll="ls -l"export PS1=’$(pwd) $ ’

This profile does the following:


Configuration files for spooler

� Uses an alias to turn on interactive mode for the rm command. Ininteractive mode, rm asks you for confirmation before it deletes thefile. The cp and mv commands also support this mode.

� Creates an alias, ll, that runs ls with the -l set. This gives a longlisting that includes the size of the files, the permissions, and so on.

� Changes the primary prompt to include the current workingdirectory (the default if you aren’t root is $). You can also changethe secondary prompt by setting PS2.

Note that you should use single quotes instead of double quotesaround the string. If you specify:export PS1="$(pwd) $ "

the pwd command is evaluated right away because double quotespermit command substitution; when you change directories, theprompt doesn’t change.

Configuration files for spoolerThis section includes the configuration files to use for remote printing,using lpr, SAMBA, and NCFTP.

Using lprPNPCMD=POSTSCRIPT

#----------------------------------------------------------------------

## The following macros are expanded for each filter command line

# $d - Device

# $m - PnP manufacture/model id# $n - Printer name

# $s - Spooldir name

# $$ - A real $#

#----------------------------------------------------------------------

FileVersion = 2

# printer name is the name that you specified in the /etc/printcap file.Filter = ps:$d:lpr -Pprinter nameFilter = phs:ps:phs-to-ps

Supported Resolution = 300 * 300,

600 * 600,



1200 * 1200

Supported PaperSize = 8500 * 11000 : Letter,

8500 * 14000 : Legal

Supported Orientation = 0 : Portrait,

1 : Landscape

Supported Intensity = 0 : Min,100 : Max

Supported InkType = 1 : "B&W",3 : "Color (CMY)",

4 : "Color (CMYK)"

Resolution = 600 * 600

PaperSize = 8500 * 11000 : Letter

Orientation = 0 : PortraitIntensity = 50

InkType = 4 : "Color (CMYK)"

NonPrintable = 500:Left, 500:Top, 500:Right, 500:Bottom

#----------------------------------------------------------------------

if PNPID=HEWLETT-PACKARDHP 850DDE

PNPSTR=MFG:HEWLETT-PACKARD;MDL:HP 8500;CLS:PRINTER;CMD:POSTSCRIPT;


8500 * 14000 : Legal,7250 * 10500 : Exec,

11000 * 17000 : B,

8262 * 11692 : A4,5846 * 8262 : A5,

7000 * 9875 : B5,

11692 * 16524 : A3

#----------------------------------------------------------------------

if PNPID=HEWLETT-PACKARDHP 25A854

PNPSTR=MFG:HEWLETT-PACKARD;MDL:HP 2500C;CLS:PRINTER;CMD:PCL,MLC,PML,POSTSCRIPT;


8500 * 14000 : Legal,7250 * 10500 : Exec,

11000 * 17000 : B,

8262 * 11692 : A4,5846 * 8262 : A5,

7000 * 9875 : B5,

11692 * 16524 : A3

#----------------------------------------------------------------------



Using NCFTPPNPCMD=POSTSCRIPT

#----------------------------------------------------------------------#

# The following macros are expanded for each filter command line

# $d - Device# $m - PnP manufacture/model id

# $n - Printer name# $s - Spooldir name

# $$ - A real $

##----------------------------------------------------------------------

FileVersion = 2# X.X.X.X is the IP address of the printer

# prt0 is the port used on the printer (in this case, port zero).

Filter = ps:$d:ncftpput -V -E X.X.X.X /prt0Filter = phs:ps:phs-to-ps

Supported Resolution = 300 * 300,600 * 600,

1200 * 1200


8500 * 14000 : Legal


1 : Landscape

Supported Intensity = 0 : Min,

100 : Max

Supported InkType = 1 : "B&W",

3 : "Color (CMY)",4 : "Color (CMYK)"

Resolution = 600 * 600PaperSize = 8500 * 11000 : Letter

Orientation = 0 : Portrait

Intensity = 50InkType = 4 : "Color (CMYK)"


#----------------------------------------------------------------------




8500 * 14000 : Legal,

7250 * 10500 : Exec,11000 * 17000 : B,

8262 * 11692 : A4,

5846 * 8262 : A5,7000 * 9875 : B5,

11692 * 16524 : A3

#----------------------------------------------------------------------



if PNPID=HEWLETT-PACKARDHP 25A854PNPSTR=MFG:HEWLETT-PACKARD;MDL:HP 2500C;CLS:PRINTER;CMD:PCL,MLC,PML,POSTSCRIPT;

Supported PaperSize = 8500 * 11000 : Letter,8500 * 14000 : Legal,

7250 * 10500 : Exec,

11000 * 17000 : B,8262 * 11692 : A4,

5846 * 8262 : A5,7000 * 9875 : B5,

11692 * 16524 : A3

#----------------------------------------------------------------------

Using SAMBAPNPCMD=POSTSCRIPT

#----------------------------------------------------------------------#

# The following macros are expanded for each filter command line

# $d - Device# $m - PnP manufacture/model id

# $n - Printer name

# $s - Spooldir name# $$ - A real $

#

#----------------------------------------------------------------------

FileVersion = 2

# You need to have an enviroment variable, DEVICE URI, set for smbspool

# to access the SAMBA shared printer.

## Form for smb command used with smbspool which is set in DEVICE URI

# No Username and password required:# - DEVICE URI = "smb://server/printer"# - DEVICE URI = "smb://workgroup/server/printer"# Username and password required:# - DEVICE URI = "smb://username:password@server/printer"# - DEVICE URI = "smb://username:password@workgroup/server/printer"## Where username = SAMBA username

# password = SAMBA password

# workgroup = SAMBA workgroup# server = SAMBA server name

# printer = SAMBA shared printer name

## Use of DEVICE URI enviroment variable allows you to set this entry for the smbspool to

# automatically look for it when it isn’t included in the commandline.

#

Filter = ps:$d:smbspool 1 NULL none 1 1Filter = phs:ps:phs-to-ps

Supported Resolution = 300 * 300,600 * 600,



1200 * 1200


8500 * 14000 : Legal


1 : Landscape

Supported Intensity = 0 : Min,100 : Max

Supported InkType = 1 : "B&W",3 : "Color (CMY)",

4 : "Color (CMYK)"

Resolution = 600 * 600

PaperSize = 8500 * 11000 : Letter

Orientation = 0 : PortraitIntensity = 50

InkType = 4 : "Color (CMYK)"


#----------------------------------------------------------------------




8500 * 14000 : Legal,7250 * 10500 : Exec,

11000 * 17000 : B,

8262 * 11692 : A4,5846 * 8262 : A5,

7000 * 9875 : B5,

11692 * 16524 : A3

#----------------------------------------------------------------------

if PNPID=HEWLETT-PACKARDHP 25A854

PNPSTR=MFG:HEWLETT-PACKARD;MDL:HP 2500C;CLS:PRINTER;CMD:PCL,MLC,PML,POSTSCRIPT;


8500 * 14000 : Legal,7250 * 10500 : Exec,

11000 * 17000 : B,

8262 * 11692 : A4,5846 * 8262 : A5,

7000 * 9875 : B5,

11692 * 16524 : A3

#----------------------------------------------------------------------


Configuration files for setting up a firewall

Configuration files for setting up a firewallIf you’ve installed the IP Filtering package from the third-partyrepository, you’ll find various documents and configuration files in/opt/ipfilter.

ipf.conf.sampleHere’s a sample configuration file for IP Filtering, which you’ll find in/opt/ipfilter/rules/ipf.conf.sample:

#

# Copyright 2001, QNX Software Systems Ltd. All Rights Reserved#

# This source code has been published by QNX Software Systems Ltd. (QSSL).

# However, any use, reproduction, modification, distribution or transfer of# this software, or any software which includes or is based upon any of this

# code, is only permitted under the terms of the QNX Open Community License# version 1.0 (see licensing.qnx.com for details) or as otherwise expressly

# authorized by a written license agreement from QSSL. For more information,

# please email [email protected].#

#

# Sample of filter rules

block in on en1 all head 100

block return-icmp(host-unr) in proto tcp from any to 10.9.0.1 port = 25 group 100block return-rst in proto tcp from any to 10.9.0.1 port = 23 group 100

# First line create a "group" head. If a packet matched a group head rule,# the packet will *only* go through that group. (and skip other groups).

# we set a group say we are interesting any packets coming in on en1 interface#

# The second line, is saying, if there is a TCP packet coming in (through en1),

# try to reach 10.9.0.1 port 25 (smtp), we block the packet, and send a ICMP# error "HOST UNREACHABLE" back.

#

# The third line, is almost the same as second, except we are interesting in# port 23 (telnet), and we will send a "TCP RESET" packet back.

block in on en0 all head 200pass in quick proto tcp from any to 10.9.0.1 port = 8823 group 100 keep state group 200

block in log proto tcp/udp from any to 10.9.0.1/32 port 20000 <> 40000 group 200

block in log body proto tcp from any to 10.9.0.1/32 flags S/SA group 200

# This is another set of rules (rule group 200). Any packet coming in from en0

# (our "external" interface), will fall in this group#

# The "pass" line, is opened a "secret port", 8823, let who ever try to contact# this port pass through. So you could run a "telnetd" on that port and just let

# your trust people know that port. The keyword "quick" make any packet matched

# this rule being proceed (pass) as of test against further rules.#

# The third line is to block any tcp/udp packet who have a port not in range

# 20000 - 40000 (our port mapping range). That means we don’t have any services



# on the gateway, except using these port to do NAT (and except the service# we run on "secret" 8823.

# Also, we "log" any blocked packet info into our internal log buffer, so

# you could use "ipmon -oI" to check it later. This rule blocks most port scanning# utils.

#

# The forth line says, if a TCP packet is coming in, and it has the SYN flag# set, but ACK not set, this is a regular TCP "handshake" packet. We block it,

# and "log body" means log the "whole" packet, so we could use ipmon to examine# it later.

ipnat.confHere’s a sample configuration file for Network Address Translation(NAT), which you’ll find in/opt/ipfilter/rules/ipnat.conf.sample:

#

# Copyright 2001, QNX Software Systems Ltd. All Rights Reserved#

# This source code has been published by QNX Software Systems Ltd. (QSSL).

# However, any use, reproduction, modification, distribution or transfer of# this software, or any software which includes or is based upon any of this

# code, is only permitted under the terms of the QNX Open Community License# version 1.0 (see licensing.qnx.com for details) or as otherwise expressly

# authorized by a written license agreement from QSSL. For more information,

# please email [email protected].#

#

## NAT rules, the sample network looks like this

#

## box1 (192.0.0.2) <---> (192.0.0.1) Gateway (10.9.0.1) <---> whole network 10

#

# The "box1" is internal machine, the "Gateway" is the one running ipfilter.so.# The "10.9.0.1" is suppose the external internet.

#

# On "Gateway", start io-net like this:#

# io-net -d epic -d speedo -p tcpip forward# ifconfig en0 10.9.0.1

# ifconfig en1 192.0.0.1

# mount -Tio-net ipfilter.so#

# Now the rules, first NAT rules

map en0 192.0.0.0/8 -> 10.9.0.1/32 proxy port ftp ftp/tcp

map en0 192.0.0.0/8 -> 10.9.0.1/32 portmap tcp/udp 20000:40000 mssclamp 1452

map en0 192.0.0.0/8 -> 10.9.0.1/32

# The first line tells NAT to using the builtin ftp-proxy

## The second line tells NAT to mapping any TCP/UDP packet on en0,



# from 192.0.0.0/8 to 10.9.0.1/32 (The "/<num>" is the netmask).# It also tells NAT map the original port into a port range

# between 20000 - 40000.

# the "mssclamp 1452" is optional, in case your external interface# has MTU less than 1500 (for example, a ppp0 running pppoe have

# MTU as 1492)

## The third line tells NAT mapping any packet if they are not

# matching above 2. This basically make ICMP packet being mapped.

rdr en1 10.9.0.1/32 port 80 -> intra.qnx.com port 80 tcp

# This "rdr" rules, is saying if the internal "box1" try to

# access gateway’s port 80, redirect it to intra.qnx.com


Glossary

Glossary 79

administrator

See superuser.

alias

A shell feature that lets you create new commands or specify yourfavorite options. For example, alias my ls=’ls -F’ creates analias called my ls that the shell replaces with ls -F.

atomic

Of or relating to atoms. :-)

In realtime systems, this refers to the requirement that an operation, orsequence of operations, be considered indivisible. For example, athread may need to move a file descriptor to a given location and readdata. These operations must be performed in an atomic manner;otherwise, another thread could preempt the original thread and movethe file descriptor to a different location, thus causing the originalthread to read data from the second thread’s position.

BIOS/ROM Monitor extension signature

A certain sequence of bytes indicating to the BIOS or ROM Monitorthat the device is to be considered an “extension” to the BIOS orROM Monitor — control is to be transferred to the device by theBIOS or ROM Monitor, with the expectation that the device willperform additional initializations.

On the x86 architecture, the two bytes 0x55 and 0xAA must be present(in that order) as the first two bytes in the device, with control beingtransferred to offset 0x0003.

bootable

An image can be either bootable or nonbootable. A bootable image isone that contains the startup code that the IPL can transfer control to.

Glossary 81

budget

In sporadic scheduling, the amount of time a thread is permitted toexecute at its normal priority before being dropped to its low priority.

buildfile

A text file containing instructions for mkifs specifying the contentsand other details of an image, or for mkefs specifying the contentsand other details of an embedded filesystem image.

bundle

A collection of products.

canonical mode

Also called edited mode or “cooked” mode. In this mode thecharacter device library performs line-editing operations on eachreceived character. Only when a line is “completely entered” —typically when a carriage return (CR) is received — will the line ofdata be made available to application processes. Contrast raw mode.

channel

A kernel object used with message passing.

In QNX Neutrino, message passing is directed towards a connection(made to a channel); threads can receive messages from channels. Athread that wishes to receive messages creates a channel (usingChannelCreate()), and then receives messages from that channel(using MsgReceivev()). Another thread that wishes to send a messageto the first thread must make a connection to that channel by“attaching” to the channel (using ConnectAttach()) and then sendingdata (using MsgSendv()).

CIFS

Common Internet File System (aka SMB) — protocol that allows aclient workstation to perform transparent file access over a network toa Windows 95/98/NT server. Client file access calls are converted toCIFS protocol requests and are sent to the server over the network.

82 Glossary

The server receives the request, performs the actual filesystemoperation, and sends a response back to the client.

CIS

Card Information Structure — a data block that maintains informationabout flash configuration. The CIS description includes the types ofmemory devices in the regions, the physical geometry of thesedevices, and the partitions located on the flash.

command completion

A shell feature that saves typing; type enough of the command’s nameto identify it uniquely, and then press Esc twice. If possible, the shellfills in the rest of the name.

command interpreter

A process that parses what you type on the command line; also knownas the shell.

common package

A package that contains files that have no bearing on the processor,such as images and text files.

common target package

A package that contains files related to building code for a specificprocessor, but that can be used on any processor. These files includeheader files or documentation specific to targeted development tools.

compound command

A command that includes a shell’s reserved words, groupingconstructs, and function definitions (e.g. ls -al | less). Contrastsimple command.

configurable limit

A special variable that stores system information. Some (e.g.PC NAME MAX) depend on the filesystem and are associated with a

path; others (e.g. SC ARG MAX) are independent of paths.

Glossary 83

configuration string

A system variable that’s like an environment variable, but is moredynamic. When you set an environment variable, the new valueaffects only the current instance of the shell and any of its childrenthat you create after setting the variable; when you set a configurationstring, its new value is immediately available to the entire system.

connection

A kernel object used with message passing.

Connections are created by client threads to “connect” to the channelsmade available by servers. Once connections are established, clientscan MsgSendv() messages over them. If a number of threads in aprocess all attach to the same channel, then the one connection isshared among all the threads. Channels and connections are identifiedwithin a process by a small integer.

The key thing to note is that connections and file descriptors (FD) areone and the same object. See also channel and FD.

console

The display adapter, the screen, and the system keyboard arecollectively referred to as the physical console. A virtual consoleemulates a physical console and lets you run more than one terminalsession at a time on a machine.

cooked mode

See canonical mode.

core dump

A file describing the state of a process that terminated abnormally.

core host package

A package that contains binaries and files specific to a processor,such as the emacs and cat utilities.

84 Glossary

core target package

A package that contains binaries and files used to generate code for aspecific processor and that are usable only on that processor.

critical section

A code passage that must be executed “serially” (i.e. by only onethread at a time). The simplest from of critical section enforcement isvia a mutex.

deadlock

A condition in which one or more threads are unable to continue dueto resource contention. A common form of deadlock can occur whenone thread sends a message to another, while the other thread sends amessage to the first. Both threads are now waiting for each other toreply to the message. Deadlock can be avoided by good designpractices or massive kludges — we recommend the good designapproach.

device driver

A process that allows the OS and application programs to make use ofthe underlying hardware in a generic way (e.g. a disk drive, a networkinterface). Unlike OSs that require device drivers to be tightly boundinto the OS itself, device drivers for QNX Neutrino are standardprocesses that can be started and stopped dynamically. As a result,adding device drivers doesn’t affect any other part of the OS —drivers can be developed and debugged like any other application.Also, device drivers are in their own protected address space, so a bugin a device driver won’t cause the entire OS to shut down.

DNS

Domain Name Service — an Internet protocol used to convert ASCIIdomain names into IP addresses. In QNX native networking, dns isone of Qnet’s builtin resolvers.

Glossary 85

dynamic bootfile

An OS image built on the fly. Contrast static bootfile.

dynamic linking

The process whereby you link your modules in such a way that theProcess Manager will link them to the library modules before yourprogram runs. The word “dynamic” here means that the associationbetween your program and the library modules that it uses is done atload time, not at linktime. Contrast static linking. See also runtimeloading.

edge-sensitive

One of two ways in which a PIC (Programmable Interrupt Controller)can be programmed to respond to interrupts. In edge-sensitive mode,the interrupt is “noticed” upon a transition to/from the rising/fallingedge of a pulse. Contrast level-sensitive.

edited mode

See canonical mode.

EOI

End Of Interrupt — a command that the OS sends to the PIC afterprocessing all Interrupt Service Routines (ISR) for that particularinterrupt source so that the PIC can reset the processor’s In ServiceRegister. See also PIC and ISR.

EPROM

Erasable Programmable Read-Only Memory — a memorytechnology that allows the device to be programmed (typically withhigher-than-operating voltages, e.g. 12V), with the characteristic thatany bit (or bits) may be individually programmed from a 1 state to a 0state. To change a bit from a 0 state into a 1 state can only beaccomplished by erasing the entire device, setting all of the bits to a 1state. Erasing is accomplished by shining an ultraviolet light throughthe erase window of the device for a fixed period of time (typically

86 Glossary

10-20 minutes). The device is further characterized by having alimited number of erase cycles (typically 10e5 - 10e6). Contrast flashand RAM.

event

A notification scheme used to inform a thread that a particularcondition has occurred. Events can be signals or pulses in the generalcase; they can also be unblocking events or interrupt events in thecase of kernel timeouts and interrupt service routines. An event isdelivered by a thread, a timer, the kernel, or an interrupt serviceroutine when appropriate to the requestor of the event.

extent

A contiguous sequence of blocks on a disk.

FD

File Descriptor — a client must open a file descriptor to a resourcemanager via the open() function call. The file descriptor then servesas a handle for the client to use in subsequent messages. Note that afile descriptor is the exact same object as a connection ID (coid,returned by ConnectAttach()).

FIFO

First In First Out — a scheduling algorithm whereby a thread is ableto consume CPU at its priority level without bounds. See alsoadaptive, round robin, and sporadic.

filename completion

A shell feature that saves typing; type enough of the file’s name toidentify it uniquely, and then press Esc twice. If possible, the shellfills in the rest of the name.

filter

A program that reads from standard input and writes to standardoutput, such as grep, sort, and wc You can use a pipe (|) tocombine filters.

Glossary 87

flash memory

A memory technology similar in characteristics to EPROM memory,with the exception that erasing is performed electrically instead of viaultraviolet light, and, depending upon the organization of the flashmemory device, erasing may be accomplished in blocks (typically64k bytes at a time) instead of the entire device. Contrast EPROMand RAM.

FQNN

Fully Qualified Node Name — a unique name that identifies a QNXNeutrino node on a network. The FQNN consists of the nodenameplus the node domain tacked together.

garbage collection

AKA space reclamation, the process whereby a filesystem managerrecovers the space occupied by deleted files and directories.

group

A collection of users who share similar file permissions.

HA

High Availability — in telecommunications and other industries, HAdescribes a system’s ability to remain up and running withoutinterruption for extended periods of time.

hard link

See link.

hidden file

A file whose name starts with a dot (.), such as .profile.Commands such as ls don’t operate on hidden files unless youexplicitly say to.

88 Glossary

image

In the context of embedded QNX Neutrino systems, an “image” canmean either a structure that contains files (i.e. an OS image) or astructure that can be used in a read-only, read/write, orread/write/reclaim FFS-2-compatible filesystem (i.e. a flashfilesystem image).

inode

Information node — a storage table that holds information about files,other than the files’ names. In order to support links for each file, thefilename is separated from the other information that describes a file.

interrupt

An event (usually caused by hardware) that interrupts whatever theprocessor was doing and asks it do something else. The hardware willgenerate an interrupt whenever it has reached some state wheresoftware intervention is required.

interrupt handler

See ISR.

interrupt latency

The amount of elapsed time between the generation of a hardwareinterrupt and the first instruction executed by the relevant interruptservice routine. Also designated as “Til”. Contrast schedulinglatency.

interrupt service routine

See ISR.

interrupt service thread

A thread that is responsible for performing thread-level servicing ofan interrupt.

Since an ISR can call only a very limited number of functions, andsince the amount of time spent in an ISR should be kept to a

Glossary 89

minimum, generally the bulk of the interrupt servicing work shouldbe done by a thread. The thread attaches the interrupt (viaInterruptAttach() or InterruptAttachEvent()) and then blocks (viaInterruptWait()), waiting for the ISR to tell it to do something (byreturning an event of type SIGEV INTR). To aid in minimizingscheduling latency, the interrupt service thread should raise itspriority appropriately.

I/O message

A message that relies on an existing binding between the client andthe resource manager. For example, an IO READ message dependson the client’s having previously established an association (orcontext) with the resource manager by issuing an open() and gettingback a file descriptor. See also connect message, context, combinemessage, and message.

I/O privity

A particular privilege, that, if enabled for a given thread, allows thethread to perform I/O instructions (such as the x86 assembler in andout instructions). By default, I/O privity is disabled, because aprogram with it enabled can wreak havoc on a system. To enable I/Oprivity, the thread must be running as root, and call ThreadCtl().

IPC

Interprocess Communication — the ability for two processes (orthreads) to communicate. QNX Neutrino offers several forms of IPC,most notably native messaging (synchronous, client/serverrelationship), POSIX message queues and pipes (asynchronous), aswell as signals.

IPL

Initial Program Loader — the software component that either takescontrol at the processor’s reset vector (e.g. location 0xFFFFFFF0 onthe x86), or is a BIOS extension. This component is responsible forsetting up the machine into a usable state, such that the startupprogram can then perform further initializations. The IPL is written in

90 Glossary

assembler and C. See also BIOS extension signature and startupcode.

IRQ

Interrupt Request — a hardware request line asserted by a peripheralto indicate that it requires servicing by software. The IRQ is handledby the PIC, which then interrupts the processor, usually causing theprocessor to execute an Interrupt Service Routine (ISR).

ISR

Interrupt Service Routine — a routine responsible for servicinghardware (e.g. reading and/or writing some device ports), forupdating some data structures shared between the ISR and thethread(s) running in the application, and for signalling the thread thatsome kind of event has occurred.

kernel

See microkernel.

level-sensitive

One of two ways in which a PIC (Programmable Interrupt Controller)can be programmed to respond to interrupts. If the PIC is operating inlevel-sensitive mode, the IRQ is considered active whenever thecorresponding hardware line is active. Contrast edge-sensitive.

linearly mapped

A term indicating that a certain memory component is entirelyaddressable by the processor. Contrast bank-switched.

link

A filename, a pointer to the file’s contents. Contrast symbolic link.

manifest

A data description of a package or repository that’s in a separate file.

Glossary 91

message

A parcel of bytes passed from one process to another. The OSattaches no special meaning to the content of a message — the data ina message has meaning for the sender of the message and for itsreceiver, but for no one else.

Message passing not only allows processes to pass data to each other,but also provides a means of synchronizing the execution of severalprocesses. As they send, receive, and reply to messages, processesundergo various “changes of state” that affect when, and for howlong, they may run.

metadata

Data about data; for a filesystem, metadata includes all the overheadand attributes involved in storing the user data itself, such as the nameof a file, the physical blocks it uses, modification and accesstimestamps, and so on.

microkernel

A part of the operating system that provides the minimal servicesused by a team of optional cooperating processes, which in turnprovide the higher-level OS functionality. The microkernel itself lacksfilesystems and many other services normally expected of an OS;those services are provided by optional processes.

mount structure

A optional, well-defined data structure (of type iofunc mount t)within an iofunc *() structure, which contains information used on aper-mountpoint basis (generally used only for filesystem resourcemanagers). See also attributes structure and OCB.

mountpoint

The location in the pathname space where a resource manager has“registered” itself. For example, the serial port resource managerregisters mountpoints for each serial device (/dev/ser1,

92 Glossary

/dev/ser2, etc.), and a CD-ROM filesystem may register a singlemountpoint of /cdrom.

mutex

Mutual exclusion lock, a simple synchronization service used toensure exclusive access to data shared between threads. It is typicallyacquired (pthread mutex lock()) and released(pthread mutex unlock()) around the code that accesses the shareddata (usually a critical section). See also critical section.

name resolution

In a QNX Neutrino network, the process by which the Qnet networkmanager converts an FQNN to a list of destination addresses that thetransport layer knows how to get to.

name resolver

Program code that attempts to convert an FQNN to a destinationaddress.

NDP

Node Discovery Protocol — proprietary QNX Software Systemsprotocol for broadcasting name resolution requests on a QNXNeutrino LAN.

network directory

A directory in the pathname space that’s implemented by the Qnetnetwork manager.

Neutrino

Name of the OS developed by QNX Software Systems.

NFS

Network FileSystem — a TCP/IP application that lets you graftremote filesystems (or portions of them) onto your local namespace.Directories on the remote systems appear as part of your localfilesystem and all the utilities you use for listing and managing files

Glossary 93

(e.g. ls, cp, mv) operate on the remote files exactly as they do onyour local files.

NMI

Nonmaskable Interrupt — an interrupt that can’t be masked by theprocessor. We don’t recommend using an NMI!

Node Discovery Protocol

See NDP.

node domain

A character string that the Qnet network manager tacks onto thenodename to form an FQNN.

nodename

A unique name consisting of a character string that identifies a nodeon a network.

nonbootable

A nonbootable OS image is usually provided for larger embeddedsystems or for small embedded systems where a separate,configuration-dependent setup may be required. Think of it as asecond “filesystem” that has some additional files on it. Since it’snonbootable, it typically won’t contain the OS, startup file, etc.Contrast bootable.

package

A directory tree of files laid out in a structure that matches where theywould be if they were transported to the root of some filesystem.

package filesystem

A virtual filesystem manager that presents a customized view of a setof files and directories to a client. The “real” files are present on somemedium; the package filesystem presents a virtual view of selectedfiles to the client.

94 Glossary

pathname prefix

See mountpoint.

pathname space mapping

The process whereby the Process Manager maintains an associationbetween resource managers and entries in the pathname space.

persistent

When applied to storage media, the ability for the medium to retaininformation across a power-cycle. For example, a hard disk is apersistent storage medium, whereas a ramdisk is not, because the datais lost when power is lost.

Photon microGUI

The proprietary graphical user interface built by QNX SoftwareSystems.

PIC

Programmable Interrupt Controller — hardware component thathandles IRQs. See also edge-sensitive, level-sensitive, and ISR.

POSIX

An IEEE/ISO standard. The term is an acronym (of sorts) for PortableOperating System Interface — the “X” alludes to “UNIX”, on whichthe interface is based.

POSIX layer calls

Convenient set of library calls for writing resource managers. ThePOSIX layer calls can handle even more of the common-casemessages and functions than the base layer calls. These calls areidentified by the iofunc *() prefix. In order to use these (and westrongly recommend that you do), you must also use the well-definedPOSIX-layer attributes (iofunc attr t), OCB (iofunc ocb t),and (optionally) mount (iofunc mount t) structures.

Glossary 95

preemption

The act of suspending the execution of one thread and starting (orresuming) another. The suspended thread is said to have been“preempted” by the new thread. Whenever a lower-priority thread isactively consuming the CPU, and a higher-priority thread becomesREADY, the lower-priority thread is immediately preempted by thehigher-priority thread.

prefix tree

The internal representation used by the Process Manager to store thepathname table.

priority inheritance

The characteristic of a thread that causes its priority to be raised orlowered to that of the thread that sent it a message. Also used withmutexes. Priority inheritance is a method used to prevent priorityinversion.

priority inversion

A condition that can occur when a low-priority thread consumes CPUat a higher priority than it should. This can be caused by notsupporting priority inheritance, such that when the lower-prioritythread sends a message to a higher-priority thread, the higher-prioritythread consumes CPU on behalf of the lower-priority thread. This issolved by having the higher-priority thread inherit the priority of thethread on whose behalf it’s working.

process

A nonschedulable entity, which defines the address space and a fewdata areas. A process must have at least one thread running in it —this thread is then called the first thread.

product

A number of packages, potentially including processor-specific andprocessor-independent packages.

96 Glossary

pty

Pseudo-TTY — a character-based device that has two “ends”: amaster end and a slave end. Data written to the master end shows upon the slave end, and vice versa. You typically use these devices whena program requires a terminal for standard input and output, and onedoesn’t exist, for example as with sockets. Pseudo terminalscommunicate over a network and appear as a real terminal to theapplication using it.

pulses

In addition to the synchronous Send/Receive/Reply services, QNXNeutrino also supports fixed-size, nonblocking messages known aspulses. These carry a small payload (four bytes of data plus a singlebyte code). A pulse is also one form of event that can be returnedfrom an ISR or a timer. See MsgDeliverEvent() for more information.

Qnet

The native network manager in QNX Neutrino.

QoS

Quality of Service — a policy (e.g. loadbalance) used to connectnodes in a network in order to ensure highly dependable transmission.QoS is an issue that often arises in high-availability (HA) networks aswell as realtime control systems.

quoting

A method of forcing a shell’s special characters to be treated assimple characters instead of being interpreted in a special way by theshell. For example, less "my file name" escapes the specialmeaning of the spaces in a filename.

RAM

Random Access Memory — a memory technology characterized bythe ability to read and write any location in the device withoutlimitation. Contrast flash and EPROM.

Glossary 97

raw mode

In raw input mode, the character device library performs no editing onreceived characters. This reduces the processing done on eachcharacter to a minimum and provides the highest performanceinterface for reading data. Also, raw mode is used with devices thattypically generate binary data — you don’t want any translations ofthe raw binary stream between the device and the application.Contrast canonical mode.

remote execution

Running commands on a machine other than your own if bothmachines are on the same network.

replenishment

In sporadic scheduling, the period of time during which a thread isallowed to consume its execution budget.

repository

A collection of bundles.

reset vector

The address at which the processor begins executing instructions afterthe processor’s reset line has been activated. On the x86, for example,this is the address 0xFFFFFFF0.

resource manager

A user-level server program that accepts messages from otherprograms and, optionally, communicates with hardware. QNXNeutrino resource managers are responsible for presenting aninterface to various types of devices, whether actual (e.g. serial ports,parallel ports, network cards, disk drives) or virtual (e.g. /dev/null,a network filesystem, and pseudo-ttys).

In other operating systems, this functionality is traditionallyassociated with device drivers. But unlike device drivers, QNXNeutrino resource managers don’t require any special arrangements

98 Glossary

with the kernel. In fact, a resource manager looks just like any otheruser-level program. See also device driver.

RMA

Rate Monotonic Analysis — a set of methods used to specify,analyze, and predict the timing behavior of realtime systems.

round robin

Scheduling algorithm whereby a thread is given a certain period oftime to run. Should the thread consume CPU for the entire period ofits timeslice, the thread will be placed at the end of the ready queuefor its priority, and the next available thread will be made READY. Ifa thread is the only thread READY at its priority level, it will be ableto consume CPU again immediately. See also adaptive, FIFO, andsporadic.

runtime loading

The process whereby a program decides while it’s actually runningthat it wishes to load a particular function from a library. Contraststatic linking.

scheduling latency

The amount of time that elapses between the point when one threadmakes another thread READY and when the other thread actually getssome CPU time. Note that this latency is almost always at the controlof the system designer.

Also designated as “Tsl”. Contrast interrupt latency.

shell

A process that parses what you type on the command line; also knownas the command interpreter.

Glossary 99

shell script

A file that contains shell commands.

simple command

A command line that contains a single command, usually a programthat you want to run (e.g. less my file). Contrast compoundcommand.

socket

A logical drive in a flash filesystem, consisting of a contiguous andhomogeneous region of flash memory.

software interrupts

Similar to a hardware interrupt (see interrupt), except that the sourceof the interrupt is software.

spilling

What happens when you try to change a file that the packagefilesystem manages: a copy of the file is transferred to the spilldirectory.

sporadic

Scheduling algorithm whereby a thread’s priority can oscillatedynamically between a “foreground” or normal priority and a“background” or low priority. A thread is given an execution budgetof time to be consumed within a certain replenishment period. Seealso adaptive, FIFO, and round robin.

startup code

The software component that gains control after the IPL code hasperformed the minimum necessary amount of initialization. Aftergathering information about the system, the startup code transferscontrol to the OS.

100 Glossary

static bootfile

An image created at one time and then transmitted whenever a nodeboots. Contrast dynamic bootfile.

static linking

The process whereby you combine your modules with the modulesfrom the library to form a single executable that’s entirelyself-contained. The word “static” implies that it’s not going to change— all the required modules are already combined into one.

superuser

The root user, which can do anything on your system. The superuserhas what Windows calls administrator’s rights.

symbolic link

A special file that usually has a pathname as its data. Symbolic linksare a flexible means of pathname indirection and are often used toprovide multiple paths to a single file. Unlike hard links, symboliclinks can cross filesystems and can also create links to directories.

system page area

An area in the kernel that is filled by the startup code and containsinformation about the system (number of bytes of memory, locationof serial ports, etc.) This is also called the SYSPAGE area.

thread

The schedulable entity under QNX Neutrino. A thread is a flow ofexecution; it exists within the context of a process.

timer

A kernel object used in conjunction with time-based functions. Atimer is created via timer create() and armed via timer settime(). Atimer can then deliver an event, either periodically or on a one-shotbasis.

Glossary 101

timeslice

A period of time assigned to a round-robin or adaptive scheduledthread. This period of time is small (on the order of tens ofmilliseconds); the actual value shouldn’t be relied upon by anyprogram (it’s considered bad design).

102 Glossary

Index

!

. (current directory) 12not supported by/dev/shmem 5flash filesystems 18

.. (parent directory) 12not supported by/dev/shmem 5flash filesystems 18

.altboot 8

.bitmap 8

.boot 8, 68

.inodes 11

.kshrc

example of 70.longfilenames 10, 12.profile

example of 70.rhosts 53<sys/*.h> See individual files

A

aliasesexamples 71

altboot file 8

B

bitmap disk-allocation file 8blocks, disk

allocating 8lost, recovering 15

boot file 8booting

Ext2 filesystem, can’t bootfrom 17

bootpd 53buildfiles

OS images, creating 5

C

cable modem 55

Index 103

Index

CD-ROM filesystem 16cdrecord 16CDs

burning 16chkfsys 15chmod 10chown 10CIFS filesystem 18cl-installer 27clients

PPPoE 56TCP/IP 45

Common Internet File System SeeCIFS

configuration stringsCS DOMAIN 33CS HOSTNAME 33CS RESOLVE 46, 59

confstr() 33conventions

node names 33typographical xi

cp

interactive mode 71CS DOMAIN 33CS HOSTNAME 33CS RESOLVE 46, 59

current directory 12

D

daemonsfile transfer 53

remote 53trivial 53

Internet 52Internet boot protocol 53Internet domain names 53line printer 53login, remote 53network routing tables 53NFS server 53shell, remote 53SNMP agent 53system status tables 53terminal session, remote 53tiny HTTP web server 53

deflate 28devb-* 16devf-* 18devices

block-specialmounting 4

unmounting 4DHCP (Dynamic Host Configuration

Protocol) 50dhcp.client 50dinit 7, 10directories

current 12prompt, including in 71

links to 12, 13circular, preventing 14

network 34parent 12spill 25

discovery 55disks

bitmap 8extents 8files, extending 9initializing 7

104 Index

Index

loader blocks 7partitions, creating 6root blocks 7structure 7

DNS (Domain Name Service)CIFS 18

Domain Name Service (DNS)CIFS 18

domain namesdaemon 53

domains 33DOS

filesystems 15drivers

network 34, 48DSL 55Dynamic Host Configuration

Protocol (DHCP) 50dynamic routing 47

E

EMANATE 57embedded filesystems, creating 18embedded systems

flash filesystems 17OS images 4temporary storage in 5

embedded web server 53environment variables

HOSTNAME 24SOCK 55

environment variablesPS1, PS2 71exports 20exports.hostname 21

Ext2 filesystem 16extents 8

F

FAT12, FAT16, FAT32filesystems 15

fdisk 6filenames

long, enabling 10maximum length 10valid characters

CD-ROM 16DOS 15Ext2 17NFS 19QNX 4 10

files/dev/shmem, under 5compressing 28copying 71decompressing 28deleting 71extending 9inodes 11links 11manifest 27names 10ownership, setting 10package filesystem, in 24spilling 25transfer daemon 53troubleshooting 28

filesystems 3CD ROM 16

Index 105

Index

CIFS 18DOS 15embedded, creating 18Ext2 16FAT12, FAT16, FAT32 15features 3flash 17mounting 4NFS 19OS image, using as 4package 22QNX 4 6

consistency, checking for 15RAM 5type, default 3unmounting 4virtual 28

firewalls 76flash filesystems 17

read-only 28flashctl 28FQNN (fully qualified node

name) 33fragmentation, reducing 9fs-cd.so 16fs-cifs 18fs-dos.so 15fs-ext2.so 17fs-nfs2 21fs-nfs3 21fs-pkg 22fs-qnx4.so 6ftpd 53fully qualified node name

(FQNN) 33

G

gateways 45getconf 10

H

hostname 39, 42HOSTNAME 24hosts 46, 59hosts

connectionschecking 60

IP addressesmapping 59

namesmust be unique 42

TCP/IP 45hosts.equiv 53

I

ifconfig 51images

filesystemcreating 18

OS 4creating 5

inetd 52inetd.conf 52inflator 28information nodes See inodesinodes 11inodes file 11

106 Index

Index

interactive mode 71interface controllers

information, displaying 61Internet

boot-protocol daemon 53daemons 52domain names

daemon 53super-server 52

io-net 34, 48, 54, 56, 58CIFS 18NFS 21Qnet 39starting 37

io-net directory 40, 59IP 45

nameservers 46IP addresses

hostsmapping 59

IP Filteringsample configuration file 76

ipstats 50, 60

L

LCP (Link Control Protocol) 57libc.so

NFS 21Link Control Protocol (LCP) 57links 11

circular, preventing 14directories 12removing 12symbolic 13

removing 14Linux Ext2 filesystem 16loader blocks 7login

remotedaemon 53

long filenames, enabling for QNX 4filesystems 10

lpd 53lpr 71ls

long listing 71lstat() 14

M

managersnetwork (io-net) 34, 48

manifests, package 27minimal routing 47mke2fs (not available) 17mkefs 18mkifs 5mount 4, 28, 37

NFS 21mv

interactive mode 71

N

name resolution 34named 53named special files 5nameservers 46

Index 107

Index

information about 59NAT (Network Address Translation)

sample configuration file 77native networking 31NCFTP, printing over 73NCP (Network Control

Protocol) 57ndp 34net 31, 39net.cfg 46netstat 51, 60network

cardfunctionality, checking 40

drivers 34, 48manager (io-net) 34, 48native (Qnet) 31routing tables

daemon 53TCP/IP 45

Network Address Translation (NAT)sample configuration file 77

Network Control Protocol(NCP) 57

Network Discovery Protocol(NDP) 34

Network File System See NFSnetworks

configuration 51directory 34status, getting 60

NFSfilesystem 19server daemon 53

nfsd 20, 53nicinfo 40, 61nodes

domain 33names 33, 42

fully qualified 33naming conventions 33remote

Qnet, contacting via 38npm-pppoe.so 56npm-qnet-compat.so 35npm-qnet-lwl4.so 36npm-qnet.so 34npm-tcpip.so 49, 51

CIFS 18npm-ttcpip.so 49, 50

CIFS, doesn’t work with 19NFS 21

O

on 38OS images 4, 8

creating 5

P

package filesystem 22packager 27packages 27packages

creating 27information about, getting 24managing 22patches 27

parent directory 12partitions

108 Index

Index

creating 6root directory 8

patches 27pathnames

indirection 13pci 54PC NAME MAX 10

permissionssetting 10

phlip 46pidin 38, 39, 58ping 42, 60pkgctl 24, 26Point-to-Point Protocol (PPP) 55,

57Point-to-Point Protocol over Ethernet

(PPPoE) 55portmap 20PPP (Point-to-Point Protocol) 55,

57pppd 56PPPoE (Point-to-Point Protocol over

Ethernet) 55pppoe-up 56pppoed 56printing

lpr 71NCFTP, over 73SAMBA, over 74spooler

configuration files 71spooling

daemon 53problems

files 28Qnet 38TCP/IP 57

processesinformation about 38running remotely 38

procnto

shared memory 5prompt, command-line

setting 71PS1, PS2 71

Q

Qnet 31diagnostic information 41protocol stack 35, 40, 42software components 34starting 37TCP/IP, compared to 45troubleshooting 38

qnetstats 41qnxbasedma.build 68qnxinstall 27QNX 4 filesystems 6

consistency, checking for 15filenames 10

R

RAM “filesystem” 5readlink() 14regular files 5Remote Procedure Call (RPC) 20repositories

third-partyfirewalls 76

Index 109

Index

resolv.conf 46, 59resolver

Qnet 34resource managers

inflator 28rftpd 53rhosts 53rlogind 53rm

interactive mode 71root blocks 7root directory 8route 47, 51routed 47, 53routing

TCP/IP 47routing protocols 47routing tables 52

daemon 53RPC (Remote Procedure Call) 20rshd 53rwhod 53

S

SAMBA, printing over 74security

firewalls 76inetd 52Qnet 36

serversInternet super-server 52PPPoE 56TCP/IP 45web, embedded 53

shared memoryprocnto 5

shellsaliases

setting 71prompt, setting 71remote

daemon 53shmem 5S IFNAME 5S IFREG 5Slinger 53SMB (Server Message Block)

protocol 18SNMP 57

agentdaemon 53

snmpd 53SOCK 55socket.so

NFS 21soft links See symbolic linkssoftware

patches 27third-party

firewalls 76spill directory 25spooler

configuration files 71SRI SNMP suite 57static routing 47symbolic links 13

removing 14SYMLOOP MAX 14system

status tablesdaemon 53

110 Index

Index

T

TCP 45TCP/IP 45

clients 45full stack 49, 51

network status 60Qnet, compared to 45routing 47servers 45software components 48stacks, running multiple 54tiny stack 49, 50

network status 60troubleshooting 57

telnetd 53terminals

remote sessiondaemon 53

tftpd 53third-party repository

firewalls 76troubleshooting

files 28Qnet 38TCP/IP 57

trusted users 53typographical conventions xi

U

umount 4, 37unlink() 14useqnet 36users

trusted 53

V

variables See also environmentvariables

virtual filesystems 28

W

web server, embedded 53

Index 111

qnx neutrinosanprotechwriting.com/software/user_guide.pdfconﬁguration issues, see the welcome to...

Documents