ChorusOS 5.0 Application Developer's Guide

Preface

This guide demonstrates the key tasks developers perform when creating applications for ChorusOS^TM systems. Hardware support, such as bus and device driver development, subsystem development, system internals, installation, general system architecture or system administration, are not covered in this guide. The guide does incorporate some of these, however, as necessary to illustrate specific aspects of ChorusOS application development.

Who Should Use This Guide

This guide is not intended to serve as an introduction to application development. It is assumed that you have experience developing applications in the C or C++ languages and are experienced in using the Solaris^TM operating environment as a development platform.

This guide includes, in its target audience, those readers unfamiliar with the development of embedded applications, or with the ChorusOS microkernel and native application programming interfaces. Rather, this guide will build on your existing knowledge. New topics are introduced in manageable pieces. Each chapter contains many solution examples. This publication has been designed to be read from cover to cover, however you will find it a valuable resource for referencing specific examples.

Before You Read This Guide

ChorusOS application development requires the ChorusOS software to be installed and configured on a host development system running the Solaris operating environment. The host development system must be connected to a target on which the ChorusOS system and applications are to be run. If the host, the target, or the connection between them is missing, you will not be able to complete the examples.

For instructions on software installation in a development environment, see the ChorusOS Installation Guide.

How This Guide Is Organized

This guide is divided into three parts and sixteen chapters, as follows:

Part 1 - Basic Application Development

This part of the guide demonstrates how to get started developing applications for ChorusOS systems.

Chapter 1, ChorusOS Development Environment describes the development environment for ChorusOS application programming. It provides the basic information and mental picture required to approach the ChorusOS development environment and tools in an effective manner.

Chapter 2, Getting Started introduces the ChorusOS development environment through the creation of a basic application designed to run on ChorusOS systems.

Chapter 3, ChorusOS Actors and Processes defines the concepts of actors and processes as they relate to ChorusOS systems.

Chapter 4, Building Makefiles and Configuring the System Image covers the configuration tools used to define what a ChorusOS system image contains and demonstrates how to include an application in a ChorusOS system image such that the application executes when the system boots.

Part 2 - ChorusOS APIs

This part of the guide describes how to build applications that use both ChorusOS microkernel and POSIX APIs, and demonstrates how to use these APIs through code examples.

Chapter 5, Introduction to ChorusOS Applications introduces the steps involved in developing applications that run on ChorusOS systems. It includes the APIs available to ChorusOS applications and the libraries available within these APIs.

Chapter 6, Building Applications for ChorusOS Systems demonstrates the use of imake macros to build different types of example ChorusOS applications written in the C and C++ languages.

Chapter 7, ChorusOS Threads deals with threads, which are the basic unit of execution on ChorusOS systems.

Chapter 8, Native Memory Management deals with the ChorusOS application programming interfaces for memory management.

Chapter 9, Scheduling and Synchronization discusses the use of the ChorusOS application programming interfaces for synchronizing threads. It also demonstrates how mutexes and semaphores are used in the ChorusOS operating system.

Chapter 10, Local Access Points deals with the concepts of local access points that are native to ChorusOS systems. It also demonstrates the use of application programming interfaces for handling LAPs.

Chapter 11, Native Messaging and Interprocess Communications deals with the concepts of interprocess communications that are native to ChorusOS systems.

Chapter 12, Time Management deals with the time management services available on ChorusOS systems and demonstrates the use of the ChorusOS APIs for managing CPU and real time.

Chapter 13, Exceptions demonstrates the use of the ChorusOS native APIs for handling thread exceptions, aborts, faults, traps, and timeouts.

Chapter 14, Analyzing System Failure : Black Boxes, Watchdog Timers, and Logging demonstrates the use of the ChorusOS APIs for diagnosing and recovering from application or system failure.

Chapter 15, Recovering From Application Failure: Hot Restart deals with the actor restart and persistent memory services available on ChorusOS systems and demonstrates the use of the ChorusOS APIs for increasing the availability of application actors.

Part 3 - Advanced Topics

This part of the guide deals with advanced topics concerning ChorusOS systems. It includes a list of the differences between similar application programming interfaces available on ChorusOS systems and the Solaris operating environment.

Chapter 16, Compatibility With POSIX Standards discusses compatibility of ChorusOS tools, devices, APIs, and protocols with those described in the POSIX standards.

Chapter 17, Performance Profiling explains how to analyze the performance of a ChorusOS system and its applications by generating a performance profile report.

Ordering Sun Documents

Fatbrain.com, an Internet professional bookstore, stocks select product documentation from Sun Microsystems, Inc.

For a list of documents and how to order them, visit the Sun Documentation Center on Fatbrain.com at http://www1.fatbrain.com/documentation/sun.

Accessing Sun Documentation Online

The docs.sun.com^SM Web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. The URL is http://www.oracle.com/technetwork/indexes/documentation/index.html.

Directory Conventions

The following table describes the directory conventions used in this book.

Table P-1 Directory Conventions


Directory	Description
`download_dir`	Directory containing the ChorusOS 5.0 download files. Example: `/home/user/downloads/ChorusOS_5.0/`
`extract_dir`	Directory containing sufficient space to extract the delivery. This directory can be a local or an NFS mounted disk that has "write" permission. Example: `/home/user/extract/`
`install_dir`	Directory where you install the ChorusOS product. Example (also default): `/opt/SUNWconn/SEW/5.0-processor_family` where `processor_family` is one of the following: `UltraSPARC`, `x86`, `PowerPC`, `MPC8xx` Note that, during installation, you can choose the installation directory other than `/opt/SUNWconn/SEW/`. However, the `5.0-processor_family` directory containing the ChorusOS directories and files is automatically created in the directory you specify.
`build_dir`	Directory where you configure and build the system image. This directory can be a local or an NFS mounted disk, but you must have "write" permission. Example: `/home/user/chorusos/build/`
`root_dir`	Directory containing the ChorusOS file system. Example: `/install_dir/chorus-family/os/root`
`mount_dir`	Directory on the host containing a file system you want to mount on a target. Example: `host`:/`install_dir`/chorus-`family`/os/root
`source_dir`	Directory containing the source files. Example: `install_dir`/chorus-`family`/src/

Note -

family is one of the following:

usparc for UltraSPARC IIi/III
x86 for Intel x86/Pentium
ppc60x for the Motorola PowerPC 60x and 750 processor family and the PowerQUICC II (mpc8260) microcontroller
mpc860 for the Motorola PowerQUICC I (mpc8xx) microcontroller.

Typographic Conventions

The following table describes the typographic changes used in this book.

Table P-2 Typographic Conventions


Typeface or Symbol	Meaning	Example
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your `.login` file. Use `ls -a` to list all files. `machine_name% you have mail.`
`AaBbCc123`	What you type, contrasted with on-screen computer output	`machine_name%` `su` `Password:`
`AaBbCc123`	Command-line placeholder: replace with a real name or value	To delete a file, type `rm` `filename`.
AaBbCc123	Book titles, new words, or terms, or words to be emphasized.	Read Chapter 6 in User's Guide. These are called class options. You must be root to do this.

Shell Prompts in Command Examples

The following table shows the default system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell.

Table P-3 Shell Prompts


Shell	Prompt
C shell prompt	`machine_name%`
C shell superuser prompt	`machine_name#`
Bourne shell and Korn shell prompt	`$`
Bourne shell and Korn shell superuser prompt	`#`