LynxOS User's Guide

z

Getting Started

This chapter provides a quick overview of basic LynxOS usage and concepts, including:

• Starting and shutting down the LynxOS Development Environment

• Starting and exiting from the X Windows

• Using PosixWorks Desk

• Using basic UNIX commands

• Creating file systems on floppy disks

• Making backups

• Starting the LynxOS environment for cross development systems

LynxOS Packages

The base LynxOS Windows cross development package includes the following
CD-ROMs:

• Open Development Environment for Windows (ODEW)

This CD-ROM contains:

- Cross Development Kit for Windows (CDK)

- Open Development Environment (ODE)

- Board Support Package (BSP)

• Messenger (only included if required by a BSP)

• Additional Components CD-ROM containing Linux ABI Compatibility Layer, GNU Zebra Routing Package, OpenSSL Encryption Package

The base LynxOS UNIX-hosted cross development package includes the following CD-ROMs:

• Cross Development Kit (CDK)

• Open Development Environment (ODE)

This CD-ROM also contains the Board Support Package (BSP) for a particular target.

• Additional Components containing Linux ABI Compatibility Layer, GNU Zebra Routing Package, OpenSSL Encryption Package

• Messenger (only included if required by a BSP)

The native development environment includes the following CD-ROMs:

• Open Development Environment (ODE)

This CD-ROM also contains the Board Support Package (BSP) for a particular target.

• X & Motif

• Messenger (only included if required by a BSP)

• Additional Components CD-ROM containing Linux ABI Compatibility Layer, GNU Zebra Routing Package, OpenSSL Encryption Package

Starting and Stopping LynxOS

When powered on, systems running LynxOS boots to a command line prompt. If password access is enabled, users are prompted to enter a login name and password. Depending on the system's user access and privileges configuration, the initial working directory is either root or the user's home directory. The pwd command displays the current working directory.

On a cross development system where LynxOS is installed on top of an existing operating system (Windows, Linux, Solaris, etc.), the user must navigate to the LynxOS installation directory and set the LynxOS environment with a SETUP script. The script SETUP.bash is used for bash shells, and SETUP.csh is used for C shells. Refer to "Setting the Cross Development Environment" for details.

To prevent system corruption, LynxOS must be powered-off with a predefined shutdown sequence. To properly shutdown LynxOS, use the following command:

# reboot -h

The -h option (halt) means that the system is not ready to power off until the following message indicates disk activity has stopped:

**** LynxOS is down ****

At this point, it is safe to power down the system.

Starting and Stopping X Windows

The native development configuration of LynxOS includes X11R6 and Motif (referred to as the "X Window System" or just "X Windows"). The X and Motif Package for LynxOS cross development systems is available separately. X Windows provides an industry standard graphical user interface (GUI) based on X11R6. The following command starts X Windows:

# startx

The keyboard sequence Ctrl-Alt-Backspace exits X Windows.

Using PosixWorks Desk

PosixWorks Desk provides quick access to LynxOS tools and utilities. Tool bars, buttons and icons facilitate management of the development environment. The folder-style file manager allows users to drag and drop files. Users can optionally install PosixWorks Desk when they install X Windows. Pressing the Help button on the main tool bar provides detailed information on PosixWorks Desk supported features.

Basic LynxOS Commands

Most basic LynxOS commands are identical to UNIX commands. This section briefly describes these basic LynxOS commands.

Further information about these commands is also available through LynxOS man pages. LynxOS man pages are accessed using the following command syntax:
man command, where command is any LynxOS command verbatim. For more information, see "LynxOS Man Pages".

Users should familiarize themselves with the following basic LynxOS commands:

Basic LynxOS Commands  

Command	Description
cd directory	Changes the current working directory to another specified directory.
cd ..	Changes the current working directory back up one level (..).
cp file1 file2	Copies the contents of file1 to file2, creating a new file named file2, while preserving the contents and name of file1 as well.
find . -name file -print	Finds files in the current working directory and its subdirectories with names containing expressions matching -name file, and prints these file names to the screen.
gcc file	Invokes the GNU C compiler (gcc), and compiles the executable code in the specified file.
less file	Displays a specified file's contents, one screen at a time. · Pressing the Enter key scrolls the screen down to the next line. · Pressing the keyboard Space Bar scrolls the screen down to the next page. · Pressing the y key scrolls the screen up to the previous line. · Pressing ctrl-B on the keyboard scrolls the screen up to the previous page. Also, the less option has a help facility that describes additional options, such as string searches, etc.
ls	Displays the current working directory's contents and file information.
man subject	Displays the man page(s) for the specified subject (command, utility or tool name).
mkdir directory	Makes a directory with the specified directory name.
mv file1 file2	Moves contents of, and renames, file1 to file2 (file1 is deleted).
pwd	Displays the path of the current working directory.
rm file	Removes the specified file.
rmdir directory_name	Removes /deletes specified directory.
vi file	Invokes the vi (visual) text editor, and creates a file with the specified file name.
reboot -a	Reboots LynxOS; the -a argument is optional, and is used to reboot the system in multi-user mode.

LynxOS Man Pages

LynxOS provides man (manual) pages for information and help with commands, utilities and tools. All LynxOS man pages are called with the syntax:

man subject

Where subject is any LynxOS command, utility or tool name. Users can enter the man command from anywhere on their systems.

LynxOS man pages are text files located in the /usr/man directory.

The LynxOS man command uses the less command to display the information one page at a time (see the description of less in the previous section). LynxOS man pages have the same user interface functionality as read-only files - users can view a text file and perform some operations on the file, such as scrolling and string searches, but cannot edit them.

While viewing the man page with the man command, users can get help with available viewing options by pressing the h key. Pressing the q key then Enter exits the help session and returns the user to the man page.

If a user is interested in a topic but is not sure what the exact commands are, a man search can be done for a keyword using the -k option:

# man -k keyword

The man command with a -k option is the least restrictive type of search - it is not case-sensitive, the keyword can be within the description of one or many commands, options, or the command name itself (as shown in the example command and its screen return below):

# man -k less
less (1) - interactive paginator files, viewing
lesskey (1) - specify key bindings for less
ltgt (3) - test for floating-point less-than or greater-than
slaveboot (1) - transfers a kernel image to a diskless SCMP client

Users can also use the more restrictive -f option with the man command --it is case sensitive--as shown in the example command and its screen return below:

# man -f less
less (1) - interactive paginator files, viewing

If neither of these options helps a user find information, the following command displays an alphabetical list of all LynxOS man pages:

# less /usr/man/windex

Creating File Systems and Making Backups

Users can create file systems and make backups to archive important data. The following steps detail creating a file system on a high-density floppy device, copying files to the floppy device, and then unmounting the device:

1. Insert an empty, high-density floppy disk into the floppy disk drive.

2. Format the floppy disk in the fdd1440.0 disk drive with the fmtflop command and -v argument (verbose mode: displays messages as the floppy is being formatted):

# fmtflop -v /dev/fd1440.0

3. Create a LynxOS file system on the floppy disk with the mkfs command:

# mkfs -v /dev/fd1440.0

4. Mount the fd1440.0 floppy disk's file system with the mount command onto the mount point directory, /mnt, by entering the following command:

# mount /dev/fd1440.0 /mnt

Note: There can only be one file system mounted on a mount point (/mnt in this example) at any given time. Use the umount command to unmount a mounted file system.

5. Copy any number of files to the mounted floppy disk file system using the following command syntax, where directory represents any directory, and file.abc and file.xyz represent any number of files from that directory:

# cp /directory/file.abc file.xyz /mnt

6. With the ls command, validate that the contents were copied to the disk.

# ls /mnt

7. Unmount the floppy disk drive when finished:

# umount /mnt

Making Backups

The tar archive utility is used to make backups of important data files on a variety of media. The type (s) of backup media chosen depends on both the development platform, and the amount of data that is to be backed up.

The following commands are examples of backing up data for a number of common configurations.

In the example below, the user's home directory is named /usr/home/mystuff. To back up the home directory's contents to a file named backup.tar, the following syntax is used:

# tar -cvf backup.tar /usr/home/mystuff

The -cvf arguments direct tar to perform the following actions:

• c - create a new tar archive

• v - provide verbose screen return (optional)

• f - direct the output to a file located in the current directory.

To back up directly to a device instead of a file, direct the output to a device node in the /dev directory. For example,

# tar -cvf /dev/device /usr/home/mystuff

To list the archival contents of the backup.tar file, the following syntax is used:

# tar -tvf backup.tar

In this example, -t is the argument that directs tar to list the archival contents of the backup.tar file.

To extract archival data in the file backup.tar and place it into /usr/home/mystuff, the following syntax is used:

# tar -xvf backup.tar /usr/home/mystuff

In the previous example, -x is the argument that directs tar to extract the archival contents of device /dev/device.

Note: If the target directory (in the example above, /usr/home/mystuff) already exists in the user's home directory, the tar command with the -x argument overwrites it with the archival data file (in the example above, backup.tar).

LynxOS Cross Development Environment

The term Cross development is the process of developing an application or kernel on a host system configuration that is different from the configuration of the target system (where the application is to be deployed).

The cross development environment provided in LynxOS includes compilers, linkers, libraries, and other development tools specific to LynxOS. The LynxOS cross development environment allows the developer the flexibility of creating LynxOS applications and kernels from a variety of platforms.

When working on a LynxOS cross development system, users must set their host system environment to use the LynxOS cross development tools before running any Makefiles or compiling applications. The cross development environment, once set, provides users the complete functionality of a native development system. The advantages of this approach is that there is no need to establish a dedicated machine for cross compiling and cross debugging an application. The application can be recompiled easily for different platforms, i.e., x86 and UNIX.

Setting the Cross Development Environment

Refer to the LynxOS Installation Guide for information on installing the Cross Development Kit (CDK) CD-ROM.

Before developing LynxOS applications on a cross development host, users must set the LynxOS cross development environment with a provided setup script. Two setup scripts are provided: SETUP.bash, which sets the bash shell environment; and SETUP.csh, which sets the C shell environment. Users must run one of these setup scripts, depending on their preferred shell, before compiling or linking LynxOS applications.

These setup scripts allow users to develop applications and run Makefiles as if they were on a native development system. With the exception of running the setup script, there is no operational difference between the application development process on a cross development or native development system.

The SETUP.bash and SETUP.csh scripts add the environment variable ENV_PREFIX to a user's PATH. The ENV_PREFIX variable specifies the directory on the host where the LynxOS development tools are located. This allows users to create their applications with LynxOS-specific compilers, linkers, and libraries. ENV_PREFIX is set to the first entry of a user's PATH to ensure that users create applications with LynxOS-specific tools.

Setting up Cross Development on UNIX Hosts

To develop LynxOS applications on a UNIX cross development host, run the setup script as follows:

1. Change to the LynxOS cross development directory. This is /usr/lynx/release/platform, where release is the LynxOS release number, and platform is the target architecture. For example:

# cd /usr/lynx/4.0.0/x86

2. Run the required setup script. For example:

For C shells:

# source SETUP.csh

For bash shells:

# . SETUP.bash

3. The setup script directs the user to the detected LynxOS development tools path. If this path is correct, type y. Otherwise, type n and enter the correct path to the LynxOS cross development tools directory.

Once the setup script has run, users can begin to develop LynxOS applications on the cross development host.

Setting up Cross Development on Windows Hosts

1. From a DOS prompt, open a bash shell. For example, type:

c:\ bash

2. Change to the LynxOS cross development directory. This is /usr/lynx/release/platform, where release is the LynxOS release number, and platform is the target architecture. For example:

# cd /usr/lynx/4.0.0/x86

3. Run the required setup script. For example:

- For C shells:

# source SETUP.csh

- For bash shells:

# . SETUP.bash

4. The setup script directs the user to the detected LynxOS development tools path. If this path is correct, type y. Otherwise, type n and enter the correct path to the LynxOS cross development tools directory.

Once the setup script has run, users can begin to develop LynxOS applications on the cross development host.

The Application Development Process

The figure below shows the basic steps in the application development process.

Application Development Process Overview

Creating Source Code with vi Text Editor

Users familiar with UNIX operating systems should already be familiar with the vi text editor. LynxOS provides vi as a part of its standard distribution.

Note: The text editor emacs is also supported by LynxOS for application development in native development environments.

For users unfamiliar with vi, this section provides a quick list of important functions.

vi is a full screen text editor used to create and modify ASCII files. There are two main modes in vi - command mode and input mode. Command mode is used for issuing short cursor placement or text selection commands. Input mode is used to add, change, or delete text in a file.

The following example shows how to create a text file, in this case a simple C program, using vi (other C program source files can be found in /src/examples):

1. Create and open a file by typing the following line:

$ vi HelloWorld.c

2. vi opens the new file HelloWorld.c in command mode. Input mode is set by pressing i.

3. Type some characters.

4. Return to command mode by pressing the Esc key.

5. Close vi, and save all changes by entering the following:

:wq

Note: To quit a file, discarding any changes, use the following command after pressing Esc: :q! To quit vi after opening the file as read-only (making no changes), enter the following command: :q

Basic vi Commands

The following table details basic vi navigation and editing commands used in Command Mode:

Basic vi Commands (Command Mode)  

To move the cursor
h	Move cursor left one character
l	Move cursor right one character
k	Move cursor up one line
j	Move cursor down one line
To delete or undo
x	Delete character at cursor
dd	Delete row at cursor
u	Undo previous action
To switch from command mode to input mode
i	Enters input mode and starts insertion before the character at the cursor.
a	Enters input mode and starts insertion after the character at the cursor.

Example vi C Program

Begin vi as shown previously and enter the following text:

#include <stdio.h>
main ()
{
int index = 10;
printf("\n\n*****************\n");
printf("Hello World! \n");
printf("*****************\n\n");
}

Now go into command mode and save the file. This example file is used in the following section, "Compiling and Linking Source Code".

Compiling and Linking Source Code

After entering and saving the source code file, the user can create an executable application by compiling and linking it with the LynxOS GNU C compiler. To compile the HelloWorld.c file, enter the following command:

$ gcc HelloWorld.c

If the program compiled without errors a default executable file called a.out is generated.

Users can rename the executable to something other than a.out by using the
-o name option as shown in the example below:

$ gcc -o HelloWorld HelloWorld.c

The resulting executable is the file HelloWorld. To execute the file, enter the following command:

$ ./HelloWorld

The executable prints the following text:

*****************
Hello World!
*******************

Debugging Source Code

LynuxWorks has two debuggers available for use with LynxOS:

• The GNU Debugger (GDB) - Provided as a standard part of the LynxOS development environment. For additional information, see the Total/db User's Guide.

• TotalView - Offered as an optional separate product; for more information on TotalView, see the TotalView User's Guide and TotalView Supplement for LynxOS Users.

Since TotalView is optional, only gdb is detailed below.

First, for GDB to function properly, the source code being debugged must be compiled using the -g GDB option as part of the compile command. This option adds debugging information to the executable. For example, to compile a source code file named HelloWorld for debugging with GDB, enter:

$ gcc -g -o HelloWorld HelloWorld.c

To start GDB, enter the following command:

$ gdb ./HelloWorld

To quit GDB, enter the following command:

Note: The GDB prompt is (gdb).

(gdb) quit

GDB does not initialize or set any default breakpoints. A breakpoint makes a program stop whenever a certain point in the program is reached during execution. Users must provide the initial breakpoint. However, it is usually convenient to set a breakpoint at main, which is done using the following command:

(gdb) break main.

GDB includes a command recognition feature that requires users to enter only as many characters of any command as make the command unique. For example, if a user wants to enter the help command, it is only necessary to type he, then press the Enter key for GDB to bring up the help list of GDB commands and their options.

Some basic GDB commands are listed below:

Basic GDB Commands

Command	Description
help	Lists GDB commands and their options. These command and option names can also be used as arguments to the help command for a display of detailed information about themselves.
list	Displays the source code.
step	Steps to the next line of source code.
break option	Sets a breakpoint at a specified line number or function.
clear option	Clears all breakpoints or the specified breakpoint option.
inspect expression	Shows the value of a data structure.
run	Runs program to completion or to the next breakpoint.
quit	Quits GDB.

Creating Custom Kernels

Users can customize individual LynxOS kernels specific to the requirements of their application. The LynxOS kernel can be optimized for maximum memory footprint economy, an advantage when memory constraints or costs are a key product requirement.

Unnecessary kernel components and/or features can be removed based upon specific application requirements.

For more information on LynxOS kernel customizations, see Chapter 7, "Customizing the Default LynxOS Kernel Configuration".

Making Final Images

The LynxOS mkimage utility can be used to create a final application or LynxOS kernel image, and LynxOS facilities for run-time. The mkimage man page and "Creating Kernel Downloadable Images (KDIs)" describe this process in detail.

Identifying LynxOS Facilities for Run-Time

Users can choose to distribute their final software product as a ROM- or RAM-based file systems containing a LynxOS kernel and an application. Users can also choose to distribute their software product as a LynxOS kernel, an application, or some subset of a development facility packages on more conventional storage media such as a disk or CD-ROM.

To distribute LynxOS in any of these configurations, users must purchase appropriate run-time royalty licenses from LynuxWorks.

Note: The number of run-time images that can be created depends on the specific license agreement with LynuxWorks. Users should refer to their specific customer agreements for details, feature capabilities, allowed time frame, and reporting procedure.

LynuxWorks, Inc. 855 Branham Lane East San Jose, CA 95138 http://www.lynuxworks.com 1.800.255.5969