OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [rtems/] [c/] [src/] [librtems++/] [README] - Blame information for rev 596

Go to most recent revision | Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.