Subversion Repositories or1k

@c

@c

@c  COPYRIGHT (c) 1988-2002.

@c  On-Line Applications Research Corporation (OAR).

@c  All rights reserved.

@c

@c  nextstep.t,v 1.3 2002/01/17 21:47:46 joel Exp

@c

@chapter Where To Go From Here

At this point, you should have successfully installed a

GNU C/C++ Cross Compilation Tools for RTEMS on your host system

as well as the RTEMS OS for the target host.  You should

have successfully linked the "hello world" program. You

may even have downloaded the executable to that target

and run it.  What do you do next?

The answer is that it depends.  You may be interested in

writing an application that uses one of the multiple

APIs supported by RTEMS.  You may need to investigate the

network or filesystem support in RTEMS.  The common

thread is that you are largely finished with this

manual and ready to move on to others.

Whether or not you decide to dive in now and write

application code or read some documentation first,

this chapter is for you.  The first section provides

a quick roadmap of some of the RTEMS documentation.

The next section provides a brief overview of the

RTEMS application structure.

@section Documentation Overview

When writing RTEMS applications, you should find the

following manuals useful because they define the

calling interface to many of the services provided

by RTEMS:

@itemize @bullet

@item @b{RTEMS Applications C User's Guide} describes the

Classic RTEMS API based on the RTEID specification.

@item @b{RTEMS POSIX API User's Guide} describes the

RTEMS POSIX API that is based on the POSIX 1003.1b API.

@item @b{RTEMS ITRON 3.0 API User's Guide} describes

the RTEMS implementation of the ITRON 3.0 API.

@item @b{RTEMS Network Supplement} provides information

on the network services provided by RTEMS.

@end itemize

In addition, the following manuals from the GNU C/C++ Cross

Compilation Toolset include information on run-time services

available.

@itemize @bullet

@item @b{Cygnus C Support Library} describes the Standard

C Library functionality provided by Newlib's libc.

@item @b{Cygnus C Math Library} describes the Standard

C Math Library functionality provided by Newlib's libm.

@end itemize

Finally, the RTEMS FAQ and mailing list archives are available

at @uref{http://www.oarcorp.com}.

There is a wealth of documentation available for RTEMS and

the GNU tools supporting it.  If you run into something

that is not clear or missing, bring it to our attention.

Also, some of the RTEMS documentation is still under

construction.  If you would like to contribute to this

effort, please contact the RTEMS Team at

@uref{mailto:rtems-users@@OARcorp.com, rtems-users@@OARcorp.com}.

If you are interested in sponsoring the development of a new

feature, BSP, device driver, port of an existing library, etc.,

please contact @uref{mailto:sales@@OARcorp.com, sales@@OARcorp.com}.

@section Writing an Application

From an application author's perspective, RTEMS applications do not

start at @code{main()}.  They begin execution at one or more

application initialization task or thread and @code{main()} is

owned by the Board Support Package.   Each API supported

by RTEMS (Classic, POSIX, and ITRON) allows the user to configure

a set of tasks that are created and started automatically

during RTEMS initialization.  The RTEMS Automatic

Configuration Generation (@code{confdefs.h}) scheme can be

used to easily generate the configuration information for

an application that starts with a single initialization task.

By convention, unless overridden, the default name of the

initialization task varies based up API.

@itemize @bullet

@item @code{Init} - single Classic API Initialization Task

@item @code{POSIX_Init} - single POSIX API Initialization Thread

@item @code{ITRON_Init} - single ITRON API Initialization Task

@end itemize

See the Configuring a System chapter in the C User's Guide for

more details.

Regardless of the API used, when the initialization task executes,

all non-networking device drivers are normally initialized and

processor interrupts are enabled.  The initialization task then

goes about its business of performing application specific

initialization.  This often involves creating tasks and other

system resources such as semaphores or message queues and allocating

memory.  In the RTEMS examples and tests, the file @code{init.c} usually

contains the initialization task.  Although not required, in

most of the examples, the initialization task completes by

deleting itself.

As you begin to write RTEMS application code, you may be confused

by the range of alternatives.  Supporting multiple tasking

APIs can make the choices confusing.  Many application groups

writing new code choose one of the APIs as their primary API

and only use services from the others if nothing comparable

is in their preferred one.  However, the support for multiple

APIs is a powerful feature when integrating code from multiple

sources.  You can write new code using POSIX services and

still use services written in terms of the other APIs.

Moreover, by adding support for yet another API, one could

provide the infrastructure required to migrate from a

legacy RTOS with a non-standard API to an API like POSIX.