Part III Transition Information for Application Developers

This part of the guide focuses on changes that affect developers and the programming environment. It describes differences, points out similarities between releases, and provides information you need to port existing software, or to write new software for the ChorusOS 5.0 operating environment. This section includes changes and enhancements that have occurred as a result of the move to FreeBSD 4.1.

Chapter 7 Additions and Changes to the Programming Environment

This chapter provides information on changes made to the programming environment in version 5.0 of the ChorusOS operating system.

Application Watchdog

The application watchdog feature provides a set of system calls that allow a ChorusOS actor to manage a two-stage watchdog timer. This timer can be used by applications or middleware to monitor their sanity.

A user or supervisor actor takes control of the timer by invoking the watchdog timer API. When under the control of an application, the two-stage watchdog timer must be reloaded periodically. If the first-stage timer expires, an interrupt is triggered, enabling the collection of diagnostic information by means of the system dump feature. The system is then restarted.

The ChorusOS operating system also provides a hardware reset watchdog timer, that is always operating. This watchdog is used to monitor the system sanity.

For more information on the watchdog timer feature, refer to "Watchdog Timer" in the ChorusOS 5.0 Application Developer's Guide.

Black Box

The ChorusOS black box feature allows applications to log events and to read the event buffer. It provides a repository for the collection and storage of event information leading up to a particular problem or circumstance.

The black box consists of a set of microkernel ring buffers into which events can be logged so that, when a problem occurs, the active buffer can be frozen for later analysis, capturing the most recent set of events.

Multiple black boxes exist, each named by a unique integer identifier. The number and sizes of black boxes on your ChorusOS operating system are tunable. A specified black box can be frozen and events can be directed into another black box.

In the event of a system crash, the black box content can be saved for further analysis with the system dump feature.

For more information on the ChorusOS black box, refer to "Software Black Box" in ChorusOS 5.0 Application Developer's Guide.

High Resolution Timer

The High Resolution Timer provides access to a fine-grained counter source for applications. This counter is used for functions such as fine-grained ordering of events in a network node, measurements of short segments of code and fault-detection mechanisms between network nodes. The high resolution timer has a resolution better than or equal to one micro-second, and does not roll over more frequently than once per day.

The High Resolution Timer API is available from both the user and microkernel execution context. Performance of read access to the timer is relative to memory speed, even if the access is made from a user execution context. This API is supported on the PowerPC 60x and UltraSPARC architectures.

Messaging

The new messaging API reuses and extends the framework provided by Sun RPC support in the Solaris^TM operating environment. Sun RPC offers the remote procedure call paradigm to implement distributed (client/server) applications.

Usually, applications requiring network communications are written using explicit network programming, (using the sockets API). The messaging API hides the implementation details as the programmer need not be aware of the transport method used between the client and the server. Therefore, applications using the messaging API can be written in a location-transparent manner.

System Instrumentation

The ChorusOS operating system provides instrumentation to inform applications of the current use of the various resources managed by the system. Several kinds of instrumentation are exported by the system. New features within system administration include:

• Extensions to /proc. For more information, refer to the proc(7S) man page.

• Extensions to sysctl. For more information, refer to the sysctl(1M) man page.

• OS_ GAUGES. For more information, see the INSTRUMENTATION(5FEA) man page.

• MKSTAT. For more information, see the INSTRUMENTATION(5FEA) man page.

For more information on these features, refer to "Administration" in the ChorusOS 5.0 Features, Architecture and Performance Overview.

System Logging

The ChorusOS operating system now provides a general message logging facility, syslog, that is used by the microkernel and by applications. This logging feature provides support for logging console activity on a target system and provides a way to store information records that are kept on persistent storage (disk) . For more information on the system logging feature, refer to "System Logging" in ChorusOS 5.0 Application Developer's Guide.

Support for Shared Libraries

Version 5.0 of the ChorusOS operating system provides support for shared libraries. Like dynamic libraries, shared libraries can be dynamically linked but unlike dynamic libraries, they are not duplicated in physical memory. When two actors, each with its own private copy of data, use the same shared library, only one instance of the library is present in physical memory.

Shared libraries use Position Independent Code (PIC) . In PIC, references to global symbols are made indirectly through symbol tables. References to global symbols, as well as local jumps, are made relative to the program counter. This code, as a result, can run anywhere in memory without being modified, but the tables must be relocated first before program execution can begin.

Position Independent Code in shared libraries performs less well than code in dynamic libraries because global symbol information is accessed through indirect references.

For more information on shared libraries, refer to "Libraries, Actors and Processes" in the ChorusOS 5.0 Application Developer's Guide.

System Events

The ChorusOS System Event API allows the ChorusOS operating system to notify applications that specified events have occurred. This feature provides a generic programming interface for event generation and delivery.

An application does not need to poll the system queues periodically but simply blocks a thread, waiting for events posted by the operating system. The ChorusOS System Event API is compatible with the corresponding Solaris Operating System API, although the event delivery mechanism is different.

The ChorusOS implementation of this API also provides extended capabilities, such as the ability to post events to separate event queues. An event monitoring application can wait for events posted to a specific event queue, or can wait for all the queues of the system event space.

Dedicated event queues implement a functional isolation between the various system event publishers and provide the foundations for a system level event channels service.

The event buffers are statically preallocated in memory pools. One dedicated pool is associated with each configured event queue. The number of available queues, the number of events that can be posted to a given queue, and the maximum size of these events must be specified at system configuration time.

The events handled by the system event framework are not required to have a fixed format. They merely have a fixed, common header, optionally followed by a set of custom, self-defined attributes.

Examples of system events include errors encountered by devices, network error reporting, device plug and removal, and notification of thresholds crossed by OS instrumentation gauges. These events are at a level at which applications and management entities can take the appropriate action.

Chapter 8 Standard Application Interfaces and POSIX Interfaces

This chapter describes the changes made to the API organization in version 5.0 of the ChorusOS operating system.

API Reorganization

A major enhancement in ChorusOS 5.0 is the provision of a POSIX API. This new POSIX API provides complete support for POSIX processes, allowing application developers to to port POSIX-compliant applications directly to ChorusOS systems.

The ChorusOS microkernel API, available in previous versions of the product, is still supported, allowing you to use microkernel API calls directly. The ChorusOS microkernel API is provided to:

• Provide more efficient access to the microkernel primitive, when real-time operating is essential.

• Allow compatibility with applications developed for earlier versions of the ChorusOS system.

This new API organisation requires that you choose to develop your applications using only one of the ChorusOS APIs:

• ChorusOS POSIX API

• ChorusOS microkernel API

The different APIs represent two different development environments and you will develop your applications on one OR the other. You are strongly encouraged to use the ChorusOS POSIX API, as this offers maximum flexibility and allows you to port POSIX applications easily. A ChorusOS POSIX application cannot access the ChorusOS microkernel API, however. If you specifically need to emphasize performance issues, or if you need to access the microkernel primitives directly, you will need to use the ChorusOS microkernel API.

It is not possible to use both the ChorusOS POSIX API and the ChorusOS microkernel API in a single application, although there are a few exceptions to this rule.

For a complete description of the API reorganization and the rules governing the new API organization, refer to "Introduction to ChorusOS Applications" in the ChorusOS 5.0 Application Developer's Guide and to the API(5FEA) man page.

Chapter 9 Tool changes

This chapter discusses changes to development tools and resources for the development environment, including compilers, linkers and debuggers. The chapter also describes how to find ChorusOS 5.0 tools.

C/C++ Compilers and Linkers

Version 5.0 of the ChorusOS operating system supports gcc version 2.97.

In addition, the C++ library and the Standard Template Library (STL) have been upgraded and are now bundled with the C++ compiler.

GDB Debugging Tool

The GNU GDB debugging tool for ChorusOS systems replaces the XRAY debugging tool used in previous versions. GDB offers the following features:

• Easy-to-use graphical user interface.

• Debugging of multithreaded user and supervisor applications, including relocatable applications.

• Flexible thread handling, including per thread breakpoints, scheduler locking, individual thread suspension and resumption, and thread names.

• Visualization of ChorusOS operating system abstractions related to debugged applications or global to the system.

• Application debugging over Ethernet or serial line, and system debugging over serial line.

• Ability to debug almost every piece of code, including the boot process, the C_OS, the drivers and the applications.

For more information on the GDB debugging tool, refer to the ChorusOS 5.0 Debugging Guide.

Insight GUI for GDB

Insight is a graphical user interface to GDB and gives you access to most of GDB's capabilities. Insight is launched by default when you launch GDB.

For more information on Insight, refer to the ChorusOS 5.0 Debugging Guide.