#
|
#
|
# $Id: README,v 1.2 2001-09-27 12:02:05 chris Exp $
|
# $Id: README,v 1.2 2001-09-27 12:02:05 chris Exp $
|
#
|
#
|
|
|
RTEMS C++ Library
|
RTEMS C++ Library
|
=================
|
=================
|
|
|
The RTEMS C++ Library or librtems++ is a wrapper for the RTEMS API.
|
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
|
The classes provide as close a match to the RTEMS C API, for
|
performance, to share the existing C documentation as much as
|
performance, to share the existing C documentation as much as
|
possible, and to allow easy tracking of any changes to the RTEMS C
|
possible, and to allow easy tracking of any changes to the RTEMS C
|
API.
|
API.
|
|
|
The C++ interface only uses RTEMS API calls. No external references
|
The C++ interface only uses RTEMS API calls. No external references
|
or internal interfaces are used. This allows the classes to be used
|
or internal interfaces are used. This allows the classes to be used
|
in separately compiled modules or applications which link to the RTEMS
|
in separately compiled modules or applications which link to the RTEMS
|
trap interface.
|
trap interface.
|
|
|
(This is the goal, which has not quite been reached. The TOD macro for
|
(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
|
micro-seconds to ticks is used, and this uses an internal global RTEMS
|
variable)
|
variable)
|
|
|
The C++ interface does not deal with RTEMS initialisation or the
|
The C++ interface does not deal with RTEMS initialisation or the
|
device driver interface. The current view is these parts of a system
|
device driver interface. The current view is these parts of a system
|
are best handled in the current manner. This means BSP for
|
are best handled in the current manner. This means BSP for
|
initialisation and the C API for drivers.
|
initialisation and the C API for drivers.
|
|
|
RTEMS C++ Classes
|
RTEMS C++ Classes
|
=================
|
=================
|
|
|
The classes map to the managers of RTEMS.
|
The classes map to the managers of RTEMS.
|
|
|
The methods have default values selected which try to fit most cases
|
The methods have default values selected which try to fit most cases
|
or follow the documented RTEMS default values. Moving from left to
|
or follow the documented RTEMS default values. Moving from left to
|
right the parameters become less used, allowing the defaults to be
|
right the parameters become less used, allowing the defaults to be
|
selected. An example is the scope parameter for most classes. This
|
selected. An example is the scope parameter for most classes. This
|
can be local or global. I assume that most RTEMS objects are local,
|
can be local or global. I assume that most RTEMS objects are local,
|
therefore it has been made the last parameter.
|
therefore it has been made the last parameter.
|
|
|
Inline methods have been used for methods which are commonly used in
|
Inline methods have been used for methods which are commonly used in
|
applications. This tries to add the minimum of overhead. For
|
applications. This tries to add the minimum of overhead. For
|
example, the methods to send or receive events are inline, while all
|
example, the methods to send or receive events are inline, while all
|
methods for control of a task are not.
|
methods for control of a task are not.
|
|
|
The RTEMS types, enumerations, and defines are used. If a new type,
|
The RTEMS types, enumerations, and defines are used. If a new type,
|
enumeration or define is made it will map directly to the RTEMS
|
enumeration or define is made it will map directly to the RTEMS
|
equivalent. For example the enumeration Scope is defined for various
|
equivalent. For example the enumeration Scope is defined for various
|
classes which can be local or global. The elements of the enumeration
|
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
|
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
|
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
|
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
|
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).
|
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
|
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
|
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
|
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
|
once. The TaskMode class allows this to occur, while also providing
|
methods to control a single mode item.
|
methods to control a single mode item.
|
|
|
The name of an object is always passed as a string. The classes turn
|
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
|
the string into a rtems_name variable. The string does not have to be
|
nul character terminated.
|
nul character terminated.
|
|
|
The RTEMS C API uses 'delete' to remove or kill an RTEMS object. This
|
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.
|
is a reserved word in C++, so the word 'destroy' is used instead.
|
|
|
Calling the classes from interrupts follows the rules of RTEMS. An
|
Calling the classes from interrupts follows the rules of RTEMS. An
|
exception introduced by the class library is the last status code.
|
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
|
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
|
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
|
a better solution needs to be found, such as interrupt calls do not set
|
the last status code.
|
the last status code.
|
|
|
RTEMS objects created by the C++ library can be operated on by C 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
|
just as any other RTEMS object. If limitations exist they should be
|
documented in under the class.
|
documented in under the class.
|
|
|
RTEMS Object Ownership
|
RTEMS Object Ownership
|
======================
|
======================
|
|
|
The concept of ownership of an object is not defined as part of the
|
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
|
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
|
message queue. Another piece of code running as part of a different
|
task can destroy the message queue. Correct behavior between the code
|
task can destroy the message queue. Correct behavior between the code
|
that creates the message queue and the code which destroy's the
|
that creates the message queue and the code which destroy's the
|
message queue must be provided by the programmer.
|
message queue must be provided by the programmer.
|
|
|
The librtems++ supports the concept of ownership of an RTEMS object.
|
The librtems++ supports the concept of ownership of an RTEMS object.
|
Only the C++ object that creates the RTEMS object can destroy it. A
|
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,
|
C++ object can connect to an existing RTEMS object and control it,
|
how-ever it can not destroy it.
|
how-ever it can not destroy it.
|
|
|
Copy constructors and assignment operators are provided to in-force
|
Copy constructors and assignment operators are provided to in-force
|
this rule.
|
this rule.
|
|
|
Ownership only applies to classes that create RTEMS objects. These
|
Ownership only applies to classes that create RTEMS objects. These
|
classes contain a flag which signals ownership of the id.
|
classes contain a flag which signals ownership of the id.
|
|
|
Timeouts
|
Timeouts
|
========
|
========
|
|
|
The timeout value is specified in micro-seconds. The classes turn the
|
The timeout value is specified in micro-seconds. The classes turn the
|
micro-second timeout value into ticks required by the RTEMS C API.
|
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 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
|
This case is tested for and the timeout value is set to one tick. All
|
other cases round down to the nearest tick.
|
other cases round down to the nearest tick.
|
|
|
Status Codes
|
Status Codes
|
============
|
============
|
|
|
All classes which form the C++ API are derived from the StatusCode
|
All classes which form the C++ API are derived from the StatusCode
|
class. This class provides a common method for handling the status
|
class. This class provides a common method for handling the status
|
code returned by RTEMS.
|
code returned by RTEMS.
|
|
|
The last returned status code is held in the StatusCode object. It
|
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
|
can be queried directly, or as a boolean. You can also obtain an
|
error string for the status code.
|
error string for the status code.
|
|
|
The setting of a status code is restricted to derived classes.
|
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
|
The last status code attribute of the class is only ever set to an
|
RTEMS defined status code.
|
RTEMS defined status code.
|
|
|
Event Class
|
Event Class
|
===========
|
===========
|
|
|
The event class allows users to send and receive events to and from
|
The event class allows users to send and receive events to and from
|
tasks.
|
tasks.
|
|
|
Events objects are by default connected the RTEMS_SELF task. A send
|
Events objects are by default connected the RTEMS_SELF task. A send
|
or receive will operate on the task currently executing.
|
or receive will operate on the task currently executing.
|
|
|
An Event object can be connected to a task using the connect method.
|
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
|
The name is the name of the task. Connection can also be achieved by
|
using the copy constructor or assignment operator.
|
using the copy constructor or assignment operator.
|
|
|
Events can be sent to a task by specifying an RTEMS task id, or by
|
Events can be sent to a task by specifying an RTEMS task id, or by
|
passing a reference to a Task object.
|
passing a reference to a Task object.
|
|
|
Interrupt Class
|
Interrupt Class
|
===============
|
===============
|
|
|
The interrupt class allows a protected virtual method of a derived
|
The interrupt class allows a protected virtual method of a derived
|
class to be an interrupt handler.
|
class to be an interrupt handler.
|
|
|
You derive from this class and provide the handler method. The next
|
You derive from this class and provide the handler method. The next
|
interrupt after the vector is caught will cause the handler method to
|
interrupt after the vector is caught will cause the handler method to
|
be entered.
|
be entered.
|
|
|
You can chain the interrupt by calling the chain method. If the old
|
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
|
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
|
(*)(void)". If it is an instance of this class, the handler method is
|
directly called. (Chaining has not been tested)
|
directly called. (Chaining has not been tested)
|
|
|
This class implements a table of pointers to the last instance to
|
This class implements a table of pointers to the last instance to
|
catch the interrupt. A static method of the class catches the
|
catch the interrupt. A static method of the class catches the
|
interrupt and re-directs the interrupt to the instance in the table.
|
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 re-direct adds a additional virtual function call and return to
|
the overhead of the interrupt. For a i386 type processor this is
|
the overhead of the interrupt. For a i386 type processor this is
|
about 12 instructions including the function call entry.
|
about 12 instructions including the function call entry.
|
|
|
Message Queue Class
|
Message Queue Class
|
===================
|
===================
|
|
|
The MessageQueue class allows message queue's to be created, or
|
The MessageQueue class allows message queue's to be created, or
|
connected too. Only the creator can destroy a message queue.
|
connected too. Only the creator can destroy a message queue.
|
|
|
The class implements, sending, urgent sending, broadcast, flushing,
|
The class implements, sending, urgent sending, broadcast, flushing,
|
and receiving.
|
and receiving.
|
|
|
Semaphore Class
|
Semaphore Class
|
===============
|
===============
|
|
|
The Semaphore class allows semaphores to be created, or connected
|
The Semaphore class allows semaphores to be created, or connected
|
too. Only the creator can destroy a semaphore.
|
too. Only the creator can destroy a semaphore.
|
|
|
All types of semaphores can be created.
|
All types of semaphores can be created.
|
|
|
(Not tested in the test code)
|
(Not tested in the test code)
|
|
|
Task Class
|
Task Class
|
==========
|
==========
|
|
|
The Task class allows tasks to be created, or connected too. Only the
|
The Task class allows tasks to be created, or connected too. Only the
|
creator can destroy a task.
|
creator can destroy a task.
|
|
|
If creating a task, derive from the Task class and provide the body
|
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
|
method. The body method is the entry point for a task. When
|
connecting to an existing task, no body method is required to be
|
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
|
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,
|
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
|
and it contains no code. The RTEMS default behaviour for a task that
|
returns occurs.
|
returns occurs.
|
|
|
The mode of a task is controlled using the TaskMode class.
|
The mode of a task is controlled using the TaskMode class.
|
|
|
The Task class allows you to start, restart, suspend, and resume a
|
The Task class allows you to start, restart, suspend, and resume a
|
task. You can control the priority, and access the note-pad
|
task. You can control the priority, and access the note-pad
|
registers. The task can also be slept using the wake_after and
|
registers. The task can also be slept using the wake_after and
|
wake_when methods.
|
wake_when methods.
|
|
|
Currently the task argument is used to pass the 'this' pointer to the
|
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
|
libraries default task body. The actual argument is held in the class
|
instance and passed to the virtual body method. This means of passing
|
instance and passed to the virtual body method. This means of passing
|
the 'this' pointer through RTEMS to the default task body requires the
|
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
|
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
|
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
|
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
|
object could stop and restart a task how-ever a notpad register is
|
lost. Any other ideas are welcome.
|
lost. Any other ideas are welcome.
|
|
|
Task Mode Class
|
Task Mode Class
|
===============
|
===============
|
|
|
The TaskMode class allows you to query or change the mode of a task.
|
The TaskMode class allows you to query or change the mode of a task.
|
The object only operates on the currently executing task.
|
The object only operates on the currently executing task.
|
|
|
The standard flags defined in RTEMS are used.
|
The standard flags defined in RTEMS are used.
|
|
|
Methods are provided to operate on a group of modes which are required
|
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
|
to be changed in a single operation. The mode and mask is specified
|
by ORing the required flags as documented in the RTEMS manual.
|
by ORing the required flags as documented in the RTEMS manual.
|
|
|
Methods are provided for accessing and controlling a specific mode.
|
Methods are provided for accessing and controlling a specific mode.
|
The returned value will only contain the requested mode's flags, and
|
The returned value will only contain the requested mode's flags, and
|
only the that mode will be changed when setting a mode.
|
only the that mode will be changed when setting a mode.
|
|
|
Timer Class
|
Timer Class
|
===========
|
===========
|
|
|
The Timer class allows timers to be created. You cannot connect to an
|
The Timer class allows timers to be created. You cannot connect to an
|
existing timer.
|
existing timer.
|
|
|
You derive from the Timer class and provide the trigger method. This
|
You derive from the Timer class and provide the trigger method. This
|
method is called when the timer triggers or times out.
|
method is called when the timer triggers or times out.
|
|
|
You can request a single shot timer using the fire_after or fire_when
|
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.
|
methods, or a periodic timer by calling the repeat_file_at method.
|
|
|
You cannot copy timer objects.
|
You cannot copy timer objects.
|
|
|
Contact
|
Contact
|
=======
|
=======
|
Send any question to me Chris Johns at cjohns@plessey.com.au, or the RTEMS
|
Send any question to me Chris Johns at cjohns@plessey.com.au, or the RTEMS
|
mailing list.
|
mailing list.
|
|
|
To Do
|
To Do
|
=====
|
=====
|
|
|
1) Develop a complete test suite (under way, cjohns@plessey.com.au).
|
1) Develop a complete test suite (under way, cjohns@plessey.com.au).
|
|
|
2) Complete wrapping the remaining RTEMS C API.
|
2) Complete wrapping the remaining RTEMS C API.
|
|
|
3) Provide light weight cout/cerr/clog classes based on printf for
|
3) Provide light weight cout/cerr/clog classes based on printf for
|
embedded systems.
|
embedded systems.
|
|
|
4) Provide a memory serial class which maps the <> operators onto
|
4) Provide a memory serial class which maps the <> operators onto
|
raw memory in network byte order independent of CPU byte order.
|
raw memory in network byte order independent of CPU byte order.
|
|
|
5) Fix the Task class so any Task object can restart a task.
|
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
|
6) Provide some frame work classes which allow actor type objects that
|
start in an ordered manner.
|
start in an ordered manner.
|
|
|
|
|
