source: rtems/c/src/librtems++/README @ bd39add

4.115
Last change on this file since bd39add was 9b4422a2, checked in by Joel Sherrill <joel.sherrill@…>, on 05/03/12 at 15:09:24

Remove All CVS Id Strings Possible Using a Script

Script does what is expected and tries to do it as
smartly as possible.

+ remove occurrences of two blank comment lines

next to each other after Id string line removed.

+ remove entire comment blocks which only exited to

contain CVS Ids

+ If the processing left a blank line at the top of

a file, it was removed.

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