source: rtems/c/src/librtems++/README @ 80847a34
Last change on this file since 80847a34 was 0074691, checked in by Joel Sherrill <joel.sherrill@…>, on Jul 31, 1997 at 10:13:29 PM

Merged very large and much appreciated patch from Chris Johns
<cjohns@…>. This patch includes the ods68302 bsp,
the RTEMS++ class library, and the rtems++ test.

  • Property mode set to 100644
File size: 9.9 KB
2#  $Id$
5RTEMS C++ Library
8The RTEMS C++ Library or librtems++ is a wrapper for the RTEMS API.
9The classes provide as close a match to the RTEMS C API, for
10performance, to share the existing C documentation as much as
11possible, and to allow easy tracking of any changes to the RTEMS C
14The C++ interface only uses RTEMS API calls.  No external references
15or internal interfaces are used.  This allows the classes to be used
16in separately compiled modules or applications which link to the RTEMS
17trap interface.
19(This is the goal, which has not quite been reached. The TOD macro for
20micro-seconds to ticks is used, and this uses an internal global RTEMS
23The C++ interface does not deal with RTEMS initialisation or the
24device driver interface.  The current view is these parts of a system
25are best handled in the current manner.  This means BSP for
26initialisation and the C API for drivers.
28RTEMS C++ Classes
31The classes map to the managers of RTEMS.
33The methods have default values selected which try to fit most cases
34or follow the documented RTEMS default values.  Moving from left to
35right the parameters become less used, allowing the defaults to be
36selected. An example is the scope parameter for most classes.  This
37can be local or global.  I assume that most RTEMS objects are local,
38therefore it has been made the last parameter.
40Inline methods have been used for methods which are commonly used in
41applications.  This tries to add the minimum of overhead.  For
42example, the methods to send or receive events are inline, while all
43methods for control of a task are not.
45The RTEMS types, enumerations, and defines are used.  If a new type,
46enumeration or define is made it will map directly to the RTEMS
47equivalent.  For example the enumeration Scope is defined for various
48classes which can be local or global. The elements of the enumeration
49are forced to the same value as the RTEMS values.  An enumeration is
50used in this case to allow the compiler to type check a little
51better. It saves having to check only RTEMS_LOCAL or RTEMS_GLOBAL is
52passed as a parameter (I am not convinced this is really needed as the
53goal was to not define anything and to only use what RTEMS provided).
55Where possible the various parts of an option bit set, or mode can be
56controlled separately or controlled as a group.  An example is the
57task mode.  The RTEMS C API allows a set of modes to be modified at
58once.  The TaskMode class allows this to occur, while also providing
59methods to control a single mode item.
61The name of an object is always passed as a string.  The classes turn
62the string into a rtems_name variable.  The string does not have to be
63nul character terminated.
65The RTEMS C API uses 'delete' to remove or kill an RTEMS object.  This
66is a reserved word in C++, so the word 'destroy' is used instead.
68Calling the classes from interrupts follows the rules of RTEMS.  An
69exception introduced by the class library is the last status code.
70There is only one last status code for each instance of the library's
71classes and it is not protected.  This needs to be watched for.  Maybe
72a better solution needs to be found, such as interrupt calls do not set
73the last status code.
75RTEMS objects created by the C++ library can be operated on by C code
76just as any other RTEMS object. If limitations exist they should be
77documented in under the class.
79RTEMS Object Ownership
82The concept of ownership of an object is not defined as part of the
83RTEMS C API.  A piece of code executing as part a task can create a
84message queue.  Another piece of code running as part of a different
85task can destroy the message queue.  Correct behavior between the code
86that creates the message queue and the code which destroy's the
87message queue must be provided by the programmer.
89The librtems++ supports the concept of ownership of an RTEMS object.
90Only the C++ object that creates the RTEMS object can destroy it.  A
91C++ object can connect to an existing RTEMS object and control it,
92how-ever it can not destroy it.
94Copy constructors and assignment operators are provided to in-force
95this rule.
97Ownership only applies to classes that create RTEMS objects.  These
98classes contain a flag which signals ownership of the id.
103The timeout value is specified in micro-seconds.  The classes turn the
104micro-second timeout value into ticks required by the RTEMS C API.
106This causes a problem for timeout values which are less than one tick.
107This case is tested for and the timeout value is set to one tick.  All
108other cases round down to the nearest tick.
110Status Codes
113All classes which form the C++ API are derived from the StatusCode
114class.  This class provides a common method for handling the status
115code returned by RTEMS.
117The last returned status code is held in the StatusCode object.  It
118can be queried directly, or as a boolean.  You can also obtain an
119error string for the status code.
121The setting of a status code is restricted to derived classes.
123The last status code attribute of the class is only ever set to an
124RTEMS defined status code.
126Event Class
129The event class allows users to send and receive events to and from
132Events objects are by default connected the RTEMS_SELF task.  A send
133or receive will operate on the task currently executing.
135An Event object can be connected to a task using the connect method.
136The name is the name of the task.  Connection can also be achieved by
137using the copy constructor or assignment operator.
139Events can be sent to a task by specifying an RTEMS task id, or by
140passing a reference to a Task object.
142Interrupt Class
145The interrupt class allows a protected virtual method of a derived
146class to be an interrupt handler.
148You derive from this class and provide the handler method.  The next
149interrupt after the vector is caught will cause the handler method to
150be entered.
152You can chain the interrupt by calling the chain method.  If the old
153handler is not an instance of this class the chain is passed as "void
154(*)(void)".  If it is an instance of this class, the handler method is
155directly called. (Chaining has not been tested)
157This class implements a table of pointers to the last instance to
158catch the interrupt.  A static method of the class catches the
159interrupt and re-directs the interrupt to the instance in the table.
160The re-direct adds a additional virtual function call and return to
161the overhead of the interrupt.  For a i386 type processor this is
162about 12 instructions including the function call entry.
164Message Queue Class
167The MessageQueue class allows message queue's to be created, or
168connected too.  Only the creator can destroy a message queue.
170The class implements, sending, urgent sending, broadcast, flushing,
171and receiving.
173Semaphore Class
176The Semaphore class allows semaphores to be created, or connected
177too.  Only the creator can destroy a semaphore.
179All types of semaphores can be created.
181(Not tested in the test code)
183Task Class
186The Task class allows tasks to be created, or connected too.  Only the
187creator can destroy a task.
189If creating a task, derive from the Task class and provide the body
190method.  The body method is the entry point for a task.  When
191connecting to an existing task, no body method is required to be
192provided.  It is how-ever required if you create a task.  This is not
193enforced by the compiler, how-ever the default body will be entered,
194and it contains no code.  The RTEMS default behaviour for a task that
195returns occurs.
197The mode of a task is controlled using the TaskMode class.
199The Task class allows you to start, restart, suspend, and resume a
200task.  You can control the priority, and access the note-pad
201registers.  The task can also be slept using the wake_after and
202wake_when methods.
204Currently the task argument is used to pass the 'this' pointer to the
205libraries default task body. The actual argument is held in the class
206instance and passed to the virtual body method. This means of passing
207the 'this' pointer through RTEMS to the default task body requires the
208actual task object to perform a restart call. This is not really the
209best solution to the problem. Another solution is to remove a notpad
210register, say 31 from the task and use it. This would mean any Task
211object could stop and restart a task how-ever a notpad register is
212lost. Any other ideas are welcome.
214Task Mode Class
217The TaskMode class allows you to query or change the mode of a task.
218The object only operates on the currently executing task.
220The standard flags defined in RTEMS are used.
222Methods are provided to operate on a group of modes which are required
223to be changed in a single operation.  The mode and mask is specified
224by ORing the required flags as documented in the RTEMS manual.
226Methods are provided for accessing and controlling a specific mode.
227The returned value will only contain the requested mode's flags, and
228only the that mode will be changed when setting a mode.
230Timer Class
233The Timer class allows timers to be created.  You cannot connect to an
234existing timer.
236You derive from the Timer class and provide the trigger method.  This
237method is called when the timer triggers or times out.
239You can request a single shot timer using the fire_after or fire_when
240methods, or a periodic timer by calling the repeat_file_at method.
242You cannot copy timer objects.
246Send any question to me Chris Johns at, or the RTEMS
247mailing list.
249To Do
2521) Develop a complete test suite (under way,
2542) Complete wrapping the remaining RTEMS C API.
2563) Provide light weight cout/cerr/clog classes based on printf for
257embedded systems.
2594) Provide a memory serial class which maps the <</>> operators onto
260raw memory in network byte order independent of CPU byte order.
2625) Fix the Task class so any Task object can restart a task.
2646) Provide some frame work classes which allow actor type objects that
265start in an ordered manner.
Note: See TracBrowser for help on using the repository browser.