Subversion Repositories openrisc_me

#

#  $Id: README,v 1.2 2001-09-27 12:02:05 chris Exp $

#

RTEMS C++ Library

=================

The RTEMS C++ Library or librtems++ is a wrapper for the RTEMS API.

The classes provide as close a match to the RTEMS C API, for

performance, to share the existing C documentation as much as

possible, and to allow easy tracking of any changes to the RTEMS C

API.

The C++ interface only uses RTEMS API calls.  No external references

or internal interfaces are used.  This allows the classes to be used

in separately compiled modules or applications which link to the RTEMS

trap interface.

(This is the goal, which has not quite been reached. The TOD macro for

micro-seconds to ticks is used, and this uses an internal global RTEMS

variable)

The C++ interface does not deal with RTEMS initialisation or the

device driver interface.  The current view is these parts of a system

are best handled in the current manner.  This means BSP for

initialisation and the C API for drivers.

RTEMS C++ Classes

=================

The classes map to the managers of RTEMS.

The methods have default values selected which try to fit most cases

or follow the documented RTEMS default values.  Moving from left to

right the parameters become less used, allowing the defaults to be

selected. An example is the scope parameter for most classes.  This

can be local or global.  I assume that most RTEMS objects are local,

therefore it has been made the last parameter.

Inline methods have been used for methods which are commonly used in

applications.  This tries to add the minimum of overhead.  For

example, the methods to send or receive events are inline, while all

methods for control of a task are not.

The RTEMS types, enumerations, and defines are used.  If a new type,

enumeration or define is made it will map directly to the RTEMS

equivalent.  For example the enumeration Scope is defined for various

classes which can be local or global. The elements of the enumeration

are forced to the same value as the RTEMS values.  An enumeration is

used in this case to allow the compiler to type check a little

better. It saves having to check only RTEMS_LOCAL or RTEMS_GLOBAL is

passed as a parameter (I am not convinced this is really needed as the

goal was to not define anything and to only use what RTEMS provided).

Where possible the various parts of an option bit set, or mode can be

controlled separately or controlled as a group.  An example is the

task mode.  The RTEMS C API allows a set of modes to be modified at

once.  The TaskMode class allows this to occur, while also providing

methods to control a single mode item.

The name of an object is always passed as a string.  The classes turn

the string into a rtems_name variable.  The string does not have to be

nul character terminated.

The RTEMS C API uses 'delete' to remove or kill an RTEMS object.  This

is a reserved word in C++, so the word 'destroy' is used instead.

Calling the classes from interrupts follows the rules of RTEMS.  An

exception introduced by the class library is the last status code.

There is only one last status code for each instance of the library's

classes and it is not protected.  This needs to be watched for.  Maybe

a better solution needs to be found, such as interrupt calls do not set

the last status code.

RTEMS objects created by the C++ library can be operated on by C code

just as any other RTEMS object. If limitations exist they should be

documented in under the class.

RTEMS Object Ownership

======================

The concept of ownership of an object is not defined as part of the

RTEMS C API.  A piece of code executing as part a task can create a

message queue.  Another piece of code running as part of a different

task can destroy the message queue.  Correct behavior between the code

that creates the message queue and the code which destroy's the

message queue must be provided by the programmer.

The librtems++ supports the concept of ownership of an RTEMS object.

Only the C++ object that creates the RTEMS object can destroy it.  A

C++ object can connect to an existing RTEMS object and control it,

how-ever it can not destroy it.

Copy constructors and assignment operators are provided to in-force

this rule.

Ownership only applies to classes that create RTEMS objects.  These

classes contain a flag which signals ownership of the id.

Timeouts

========

The timeout value is specified in micro-seconds.  The classes turn the

micro-second timeout value into ticks required by the RTEMS C API.

This causes a problem for timeout values which are less than one tick.

This case is tested for and the timeout value is set to one tick.  All

other cases round down to the nearest tick.

Status Codes

============

All classes which form the C++ API are derived from the StatusCode

class.  This class provides a common method for handling the status

code returned by RTEMS.

The last returned status code is held in the StatusCode object.  It

can be queried directly, or as a boolean.  You can also obtain an

error string for the status code.

The setting of a status code is restricted to derived classes.

The last status code attribute of the class is only ever set to an

RTEMS defined status code.

Event Class

===========

The event class allows users to send and receive events to and from

tasks.

Events objects are by default connected the RTEMS_SELF task.  A send

or receive will operate on the task currently executing.

An Event object can be connected to a task using the connect method.

The name is the name of the task.  Connection can also be achieved by

using the copy constructor or assignment operator.

Events can be sent to a task by specifying an RTEMS task id, or by

passing a reference to a Task object.

Interrupt Class

===============

The interrupt class allows a protected virtual method of a derived

class to be an interrupt handler.

You derive from this class and provide the handler method.  The next

interrupt after the vector is caught will cause the handler method to

be entered.

You can chain the interrupt by calling the chain method.  If the old

handler is not an instance of this class the chain is passed as "void

(*)(void)".  If it is an instance of this class, the handler method is

directly called. (Chaining has not been tested)

This class implements a table of pointers to the last instance to

catch the interrupt.  A static method of the class catches the

interrupt and re-directs the interrupt to the instance in the table.

The re-direct adds a additional virtual function call and return to

the overhead of the interrupt.  For a i386 type processor this is

about 12 instructions including the function call entry.

Message Queue Class

===================

The MessageQueue class allows message queue's to be created, or

connected too.  Only the creator can destroy a message queue.

The class implements, sending, urgent sending, broadcast, flushing,

and receiving.

Semaphore Class

===============

The Semaphore class allows semaphores to be created, or connected

too.  Only the creator can destroy a semaphore.

All types of semaphores can be created.

(Not tested in the test code)

Task Class

==========

The Task class allows tasks to be created, or connected too.  Only the

creator can destroy a task.

If creating a task, derive from the Task class and provide the body

method.  The body method is the entry point for a task.  When

connecting to an existing task, no body method is required to be

provided.  It is how-ever required if you create a task.  This is not

enforced by the compiler, how-ever the default body will be entered,

and it contains no code.  The RTEMS default behaviour for a task that

returns occurs.

The mode of a task is controlled using the TaskMode class.

The Task class allows you to start, restart, suspend, and resume a

task.  You can control the priority, and access the note-pad

registers.  The task can also be slept using the wake_after and

wake_when methods.

Currently the task argument is used to pass the 'this' pointer to the

libraries default task body. The actual argument is held in the class

instance and passed to the virtual body method. This means of passing

the 'this' pointer through RTEMS to the default task body requires the

actual task object to perform a restart call. This is not really the

best solution to the problem. Another solution is to remove a notpad

register, say 31 from the task and use it. This would mean any Task

object could stop and restart a task how-ever a notpad register is

lost. Any other ideas are welcome.

Task Mode Class

===============

The TaskMode class allows you to query or change the mode of a task.

The object only operates on the currently executing task.

The standard flags defined in RTEMS are used.

Methods are provided to operate on a group of modes which are required

to be changed in a single operation.  The mode and mask is specified

by ORing the required flags as documented in the RTEMS manual.

Methods are provided for accessing and controlling a specific mode.

The returned value will only contain the requested mode's flags, and

only the that mode will be changed when setting a mode.

Timer Class

===========

The Timer class allows timers to be created.  You cannot connect to an

existing timer.

You derive from the Timer class and provide the trigger method.  This

method is called when the timer triggers or times out.

You can request a single shot timer using the fire_after or fire_when

methods, or a periodic timer by calling the repeat_file_at method.

You cannot copy timer objects.

Contact

=======

Send any question to me Chris Johns at cjohns@plessey.com.au, or the RTEMS

mailing list.

To Do

=====

1) Develop a complete test suite (under way, cjohns@plessey.com.au).

2) Complete wrapping the remaining RTEMS C API.

3) Provide light weight cout/cerr/clog classes based on printf for

embedded systems.

4) Provide a memory serial class which maps the <> operators onto

raw memory in network byte order independent of CPU byte order.

5) Fix the Task class so any Task object can restart a task.

6) Provide some frame work classes which allow actor type objects that

start in an ordered manner.