test

ChorusOS 5.0 Application Developer's Guide

Chapter 2 Getting Started

This chapter introduces the ChorusOS development environment through the creation of a basic application designed to run on ChorusOS systems. After implementing the procedures and examples in this chapter, you will have a ChorusOS system ready for initial development and a basic grasp of the tools, of the configuration and of the steps involved in application development for ChorusOS systems.

It is assumed here that your development environment meets the following requirements.

If these requirements have not yet been met, you must make sure they are satisfied before trying the examples and procedures described in this guide. Before continuing, ensure that your system administrator has set up the host and target systems for your use, or follow the instructions provided in the ChorusOS Installation Guide for basic installation, building and booting a standard ChorusOS system image, and setting up access to the target system console.

General Principles

When writing applications for ChorusOS systems, there are certain principles and conventions you should be aware of. These are described in the following sections.

Programming Conventions

The ChorusOS operating system provides a large variety of services that you can use in your applications. These services are accessed as C routines. C header files provide the required constants, types, and prototype definitions. The high modularity of the ChorusOS operating system is reflected by the numerous header files. However, in the following examples a global header file, named chorus.h, is used for simplicity. The chorus.h header file collects most of the required header files. Refer to the man pages to obtain the actual minimum header files required for each service.

Most ChorusOS operating system constants are prefixed with K_. ChorusOS operating system error codes are prefixed with with K_E.

Note -

Constants and error codes are all written in uppercase.

Most specific data types are prefixed by Kn. When type names are composed of several lexemes, the first letter of each lexeme is written in uppercase while the remaining letters are in lowercase, as in KnRgnDesc (region descriptor).

To compile and link an application, the following information must be specified in the makefile:

Program Entry Point

To initialize libraries correctly before starting the execution of application code, the program entry point must be set to _start. Once the initialization of libraries is completed, _start calls the _main routine, which initializes variables in C++ programs. The main() routine is then called. The _main routine manages any double calling at program initialization.

Libraries

To determine which ChorusOS operating system libraries to use, consider the following points:

Supervisor Application Binaries

Because supervisor applications share the same supervisor address space, they are built as relocatable binaries which are linked dynamically prior to loading. Supervisor applications jump into the system to access system services, that is, they do not trap.

Note -

When programming supervisor applications, remember that no memory protection is provided between applications. A badly written supervisor application that accesses addresses outside its own address space can corrupt any supervisor region and cause unexpected behavior such as a system crash or reboot.

User Application Binaries

Although user applications use private address spaces, they are also built as relocatable binaries. This simplifies the building of supervisor and user applications. Unlike supervisor applications, user applications trap to the system to access system services.

User applications built as relocatable binaries can run in either VIRTUAL_ADDRESS_SPACE or in non-virtual address space (flat memory). If they were relocated on the host, these binaries cannot run in flat memory mode, which does not support private address spaces.

Note -

Although it is possible to relocate user applications on the host, the ChorusOS operating system provides no specific tools to achieve this.

The link address (relocatable) of the user applications and the size of the user address space are board-dependent. User applications are also linked dynamically prior to loading.

Before Starting

Before attempting any examples in this chapter, ensure that you have:

Target File System Setup

This section walks the user through building a root file system on the host, sharing the root file system through NFS, and mounting it on the target both manually and automatically at boot time.

Building the Target NFS Root

The root makefile target (located in the build directory) enables you to copy files from components into the root directory.

Because the EXAMPLES component contains binary files that the target must see, use the make root command to copy the binary files of the EXAMPLES component into the root directory as follows: 

host% make root

The root directory now contains the binary files of the EXAMPLES component. You can run this component on any target system where the root directory can be NFS mounted.

Creating a Basic Application

When you build a standard ChorusOS sytem image on your target hardware system, a build directory is created in your work directory for each source component included in the system image. Each build directory contains the binary code for its associated component.

Note -

No directories are created for binary components.

Creating a Basic "Hello" Application

Create a src subdirectory on your host.

To create the basic "hello" application,

  1. Create the following files in the src directory:

    • hello.c, this source file will say "hello" and is written as follows: 

      #include <stdio.h>

int main()
{
      /* Print the message */
  printf("Hello World\n");
  
  return 0;
}

    • Imakefile. This file provides the rules to build the application and contains the following:

      UserActorTarget(hello_u,hello.o,)
SupActorTarget(hello_s, hello.o,)

      The Imakefile declares:

      • The source files to be compiled (implicitly).

      • The libraries to be used (only standard libraries are used).

      • That you want to build both a user and a supervisor application called hello.

  2. Use the ChorusOSMkMf command to create a make file that will build your application:

    % ChorusOSMkMf build_dir

    The ChorusOSMkMf command should be located in your PATH. See "Setting Environment Variables" in the ChorusOS 5.0 Installation Guide for information on how to modify your PATH.

  3. Build your application:

    % make

Running the Application

Use the C_INIT loading facility to run the application dynamically, as follows:

ChorusOS operating system applications are loaded and locked in memory when they start. This means that physical memory for the application's text, data, and stack must be available at load time. The memstat command of C_INIT can be used to check if sufficient physical memory is available on the target system.

Debugging in ChorusOS Systems

The ChorusOS operating system provides two levels of debugging:

Application and system debugging are both achieved using the GDB debugger for ChorusOS systems and its graphical user interface, Insight.

The ChorusOS 5.0 Debugging Guide provides detailed information on how to debug applications and your ChorusOS system.