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.
The host development tool chain is installed and configured on your development host.
You have built and booted a standard ChorusOS system image on your target hardware system.
You have access to the target console from your development host.
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.
When writing applications for ChorusOS systems, there are certain principles and conventions you should be aware of. These are described in the following sections.
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.
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:
The header file directories and compilation flags.
The program entry point.
The libraries to be linked to the program according to the services used by the:
Application
Environment present on the target system
Actor type (user or supervisor)
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.
To determine which ChorusOS operating system libraries to use, consider the following points:
Which APIs (POSIX or microkernel) are to be used by the application.
What additional libraries are required.
In which address space will the application execute.
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.
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.
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.
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 attempting any examples in this chapter, ensure that you have:
The JavaTM Runtime Environment (version 1.2 or above) on the host workstation.
Names of the host workstation, boot server, and target system.
Root passwords for the host workstation and boot server.
IP addresses of the host workstation, boot server and target system.
Ethernet address of the target system.
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.
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.
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.
No directories are created for binary components.
Create a src subdirectory on your host.
To create the basic "hello" application,
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.
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.
Build your application:
% make
Use the C_INIT loading facility to run the application dynamically, as follows:
Copy the executable application files into the root_dir/bin directory:
% cp hello_s root_dir/bin
This step is important because the applications must be in a directory on the host that is exported to the target system.
Start the hello supervisor actor:
% rsh target_name /bin/hello_s
This command returns the PID of the new application.
The ChorusOS operating system provides two levels of debugging:
System debugging
Application 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.