ChorusOS 5.0 Application Developer's Guide

Chapter 5 Introduction to ChorusOS Applications

This chapter introduces the steps involved in developing applications to run on ChorusOS systems. It includes the APIs available to ChorusOS applications and the libraries available within these APIs.

About ChorusOS Applications

The ChorusOS operating system provides an environment for applications running on a network of target machines, controlled by a remote host.

The target system runs the ChorusOS operating system and provides the execution environment.
The host machine provides the development and debugging environment. The user can develop the applications on the host and from the host, start and debug applications on the target.

Application Types

The ChorusOS operating system supports three kinds of applications:

POSIX processes

Most of the applications running on ChorusOS systems will be POSIX processes. These applications have access to pure POSIX APIs, a few "POSIX-like" extended APIs, and a small number of restricted microkernel system calls.
ChorusOS actors

These applications run on top of the microkernel and are restricted to the microkernel API. ChorusOS actors include drivers, subsystem events, and protocol stacks.
ChorusOS 4.x Legacy applications

These applications are supported for backward compatibility and use the same APIs they used as in previous versions of the ChorusOS system. Although these applications are supported in ChorusOS 5.0, you are encouraged to move such applications to the POSIX level, using the standard POSIX APIs.

Note -

The different groups of APIs represent different development environments - you can develop new applications on one or the other. You are strongly encouraged to use the ChorusOS POSIX API because this offers maximum flexibility and enables porting of POSIX applications with relative ease. A ChorusOS POSIX application cannot access the ChorusOS microkernel API, (apart from a few restricted calls, which are described at the end of this chapter). If you specifically need to emphasize performance issues, or if you require access to the microkernel primitives directly, you should use the ChorusOS microkernel API.

ChorusOS APIs

This section provides an overview of the programming interfaces available to applications developed for ChorusOS systems. The programming interface may differ from one application to another, depending on:

Application type - whether it is a POSIX process, a ChorusOS actor, or an embedded actor.
Execution mode - whether running in user or supervisor space.
Execution structure - whether it contains one or more threads.

Naming Conventions

Library names used in the ChorusOS operating system adhere to the following conventions with regard to their suffixes:

`.u.a`	These static libraries can only be used to build actors that will be loaded in a user address space.
`.s.a`	These static libraries can only be used to build actors that will be loaded in the supervisor address space.
`.a`	These static libraries can be used to build either user or supervisor actors or processes.
`.so`	These libraries are shared or dynamic and can be used to build either user or supervisor actors or processes.

All header file and library pathnames listed in the following subsections are related to the installation path of your ChorusOS system, typically, install_dir/chorus-target.

ChorusOS Microkernel APIs

The programming environment of ChorusOS actors consists of the following interfaces:

Microkernel API
Private Data API
Standard-C API
Console I/O API

The ChorusOS actor APIs enable you to build two kinds of applications:

Embedded actors
Standard actors

Embedded actors:

Embedded user actors use the embedded library:

kernel/lib/embedded/libebd.u.a
Embedded supervisor actors use the embedded library:

kernel/lib/embedded/libebd.s.a

Standard actors:

Standard actors not linked to the embedded library use the library:

os/lib/libc.a

Note that this is the same library used by POSIX processes.

ChorusOS POSIX APIs and Extensions

The programming environment of POSIX processes includes the standard POSIX APIs and a number of POSIX extensions that can be accessed directly by any process.

POSIX API Libraries

Certain libraries (libc and libstdc++, for example) are implicitly provided when you select the appropriate Imakefile rule (see "The imake Environment"). Other libraries must be explicitly stated in the Imakefile.

The libraries to which a process has access may be either static (.a) or shared (.so). Whether the process uses a static or shared library depends on the rule selected in the Imakefile. Shared processes use libc.so.

The following sections describe all libraries that can be used by a process. Note that the libraries can be accessed by either a user or supervisor actor or process.

libc.a/libc.so and libstdc++.a

The os/lib/libc.a and os/lib/libc.so libraries are automatically included by any process or actor and include the following APIs:

Private Data API
LAP API
MIPC API
IPC API
Standard C API
POSIX I/O API
POSIX Network API

Note -

C++ actors or processes have access to the same APIs through the C++ library (os/lib/libstdc++.a).

Other Libraries

The following libraries can be accessed by either a supervisor or user process or actor. These libraries must be explicitly included in your Imakefile and contain the full pathname.

To add a library to an Imakefile, $(OS_DIR)/lib/lib<libraryname>.a or $(OS_DIR)/lib/lib<libraryname>.so to the relevant rule.

Table 5-1 Static libraries (.a)


Library name and path	Description
`os/lib/libcrypt.a`	Encryption and decryption library
`os/lib/libleamalloc.a`	Doug lea malloc library
`os/lib/libldap.a`	LDAP library
`os/lib/libnvpair.a`	Solaris-like name/value pair companion library
`os/lib/libnsl.a`	Network services library (symbolic link to `libresolv.a`)
`os/lib/libpam.a`	Interface library for pluggable authentication module (PAM)
`os/lib/libresolv.a`	Network services library
`os/lib/librpc.a`	RPC library
`os/lib/libpthreads.a`	POSIX `pthread` library
`os/lib/libsysevent.a`	Solaris-like `sysevent` API
`os/lib/libftpd.a`	FTP services
`os/lib/libmd.a`	Netscape secure hash algorithms.
`os/lib/libns.a`	ChorusOS Name Service (NS)
`os/lib/libtelnetd.a`	Telnet services
`os/lib/libyp.a`	Yellow pages services `(xdr_ypXXX)`
`os/lib/libutil.a`	This library includes the functions `openpty()` and `creat()`.
`os/lib/libmsun.a`	This library includes the function `ilogb()` which returns the binary exponent of a non-zero double value.

Note -

Using the libsysevent.a library dictates that you use the libnvpair.a, librpc.a and libpthreads.a libraries too.

Table 5-2 Shared libraries (.so)


Library name and path	Description
`os/lib/libldap.so`	LDAP library
`os/lib/libnsl.so`	Network services library (symbolic link to `libresolv.so`)
`os/lib/libpam.so`	Interface library for PAM
`os/lib/libpthreads.so`	POSIX `pthread` library
`os/lib/libresolv.so`	Network services library
`os/lib/librpc.so`	RPC library

POSIX Extensions

The extensions to the standard POSIX APIs can be divided into two groups:

Restricted microkernel calls
POSIX-like extended services

The restricted microkernel calls are directly available from the libc.a or libc.so libraries and include the following APIs:

MIPC
IPC
LAP

To add POSIX-like extended services, you must specify the required library in your Imakefile. These services include the following APIs:

Blackbox
SysEvent
LDAP

Multithreading

The embedded libraries (libebd.u.a and libebd.s.a) and the libc.a and libstdc++.a libraries have been made thread-safe to support multithreaded actors. Multithreading is managed by the library in the following way:

Protecting shared variables with mutexes.
Using the Private Data library to maintain private variables per thread (for errno management, see the next section).

Defining errno as a single global variable for an actor is not suitable for multithreaded actors. Situations can arise where a thread, when examining errno on return from a failed system call, concludes that the call failed for the wrong reason (because the global errno was changed by another system call in another thread in the meantime). Some programs also test errno rather than system call return values to detect errors.

To prevent global errno changes by another system call, the header file errno.h (which is exported by the POSIX environment) should be included in any source file using errno. This will result in a separate value of errno for each thread.

Mathematical API

Routines implemented in the mathematical API can be used by actors that use the microkernel API and by processes that use the POSIX API.

The mathematical API is located in kernel/lib/libm.

The mathematical library is libm.a.

ChorusOS API Restrictions

The ChorusOS operating system provides a set of application programming interfaces (APIs) for the development of everything from board support packages to network drivers and subsystems to POSIX compatible applications. However, indescriminately mixing functions from different APIs in the same program could lead to disaster.

The ChorusOS API Classification model defines ChorusOS APIs in terms of specific classes and highlights the restrictions that exist between APIs of each class. For the complete API Classfication model, see the API(5FEA) man page.