source: rtems/doc/user/concepts.t @ d5671b1

4.104.114.95
Last change on this file since d5671b1 was d5671b1, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 29, 2008 at 9:37:00 PM

2008-01-29 Joel Sherrill <joel.sherrill@…>

  • user/.cvsignore, user/Makefile.am, user/c_user.texi, user/concepts.t, user/conf.t, user/dirstat.texi, user/stackchk.t, user/task.t, user/userext.t: Add new Object Services collection. Tidy up some configuration documentation from earlier changes.
  • user/object.t: New file.
  • Property mode set to 100644
File size: 13.5 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@c
10@c  The following figure was replaced with an ASCII equivalent.
11@c    Figure 2-1 Object ID Composition
12@c
13
14@chapter Key Concepts
15
16@section Introduction
17
18The facilities provided by RTEMS are built upon a
19foundation of very powerful concepts.  These concepts must be
20understood before the application developer can efficiently
21utilize RTEMS.  The purpose of this chapter is to familiarize
22one with these concepts.
23
24@section Objects
25
26@cindex objects
27
28RTEMS provides directives which can be used to
29dynamically create, delete, and manipulate a set of predefined
30object types.  These types include tasks, message queues,
31semaphores, memory regions, memory partitions, timers, ports,
32and rate monotonic periods.  The object-oriented nature of RTEMS
33encourages the creation of modular applications built upon
34re-usable "building block" routines.
35
36All objects are created on the local node as required
37by the application and have an RTEMS assigned ID.  All objects
38have a user-assigned name.  Although a relationship exists
39between an object's name and its RTEMS assigned ID, the name and
40ID are not identical.  Object names are completely arbitrary and
41selected by the user as a meaningful "tag" which may commonly
42reflect the object's use in the application.  Conversely, object
43IDs are designed to facilitate efficient object manipulation by
44the executive.
45
46@subsection Object Names
47
48@cindex object name
49@findex rtems_object_name
50
51An object name is an unsigned thirty-two bit entity
52associated with the object by the user.  The data type
53@code{@value{DIRPREFIX}name} is used to store object names.
54
55@findex rtems_build_name
56
57Although not required by RTEMS, object names are often
58composed of four ASCII characters which help identify that object.
59For example, a task which causes a light to blink might be
60called "LITE".  The @code{@value{DIRPREFIX}build_name} routine
61is provided to build an object name from four ASCII characters. 
62The following example illustrates this:
63
64@ifset is-C
65@example
66rtems_object_name my_name;
67
68my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
69@end example
70@end ifset
71
72@ifset is-Ada
73@example
74My_Name : RTEMS.Name;
75
76My_Name = RTEMS.Build_Name( 'L', 'I', 'T', 'E' );
77@end example
78@end ifset
79
80However, it is not required that the application use ASCII
81characters to build object names.  For example, if an
82application requires one-hundred tasks, it would be difficult to
83assign meaningful ASCII names to each task.  A more convenient
84approach would be to name them the binary values one through
85one-hundred, respectively.
86
87@ifset is-C
88@findex rtems_get_object_name
89
90RTEMS provides a helper routine, @code{@value{DIRPREFIX}get_object_name},
91which can be used to obtain the name of any RTEMS object using just
92its ID.  This routine attempts to convert the name into a printable string.
93
94The following example illustrates the use of this method to print
95an object name:
96
97@example
98#include <rtems.h>
99#include <rtems/bspIo.h>
100
101void print_name(rtems_id the_object)
102@{
103  char  buffer[10];   /* name assumed to be 10 characters or less */
104  char *result;
105
106  result = rtems_get_object_name( id, sizeof(buffer), buffer );
107  printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
108@}
109@end example
110@end ifset
111
112
113@subsection Object IDs
114
115@cindex object ID
116@cindex object ID composition
117@findex rtems_id
118
119@need 3000
120
121An object ID is a unique unsigned thirty-two bit
122entity composed of three parts: object class, node, and index.
123The data type @code{@value{DIRPREFIX}id} is used to store object IDs.
124
125
126@ifset use-ascii
127@example
128@group
129     31        26 25              16 15                             0
130     +-----------+------------------+-------------------------------+
131     |           |                  |                               |
132     |   Class   |       Node       |             Index             |
133     |           |                  |                               |
134     +-----------+------------------+-------------------------------+
135@end group
136@end example
137@end ifset
138
139@ifset use-tex
140@sp 1
141@tex
142\centerline{\vbox{\offinterlineskip\halign{
143\strut#&
144\hbox to 0.50in{\enskip#}&
145\hbox to 0.50in{\enskip#}&
146#&
147\hbox to 0.50in{\enskip#}&
148\hbox to 0.50in{\enskip#}&
149#&
150\hbox to 1.00in{\enskip#}&
151\hbox to 1.00in{\enskip#}&
152#\cr
153\multispan{9}\cr
154\multispan{2}31\hfil&\multispan{2}\hfil26\enskip&
155 \multispan{1}\enskip25\hfil&\multispan{2}\hfil16\enskip&
156 \multispan{1}\enskip15\hfil&\multispan{2}\hfil0\cr
157&&&&&&&&&\cr
158}}\hfil}
159\centerline{\vbox{\offinterlineskip\halign{
160\strut\vrule#&
161\hbox to 0.50in{\enskip#}&
162\hbox to 0.50in{\enskip#}&
163\vrule#&
164\hbox to 0.50in{\enskip#}&
165\hbox to 0.50in{\enskip#}&
166\vrule#&
167\hbox to 0.50in{\enskip#}&
168\hbox to 0.50in{\enskip#}&
169\vrule#\cr
170\multispan{9}\cr
171\noalign{\hrule}
172&&&&&&&&&\cr
173&\multispan{2}\hfil Class\hfil&&
174 \multispan{2}\hfil Node\hfil&&
175 \multispan{2}\hfil Index\hfil&\cr
176&&&&&&&&&\cr
177\noalign{\hrule}
178}}\hfil}
179@end tex
180@end ifset
181
182@ifset use-html
183@html
184<CENTER>
185  <TABLE COLS=6 WIDTH="60%" BORDER=0>
186<TR><TD ALIGN=left><STRONG>31</STRONG></TD>
187    <TD ALIGN=right><STRONG>26</STRONG></TD>
188    <TD ALIGN=left><STRONG>25</STRONG></TD>
189    <TD ALIGN=right><STRONG>16</STRONG></TD>
190    <TD ALIGN=left><STRONG>15</STRONG></TD>
191    <TD ALIGN=right><STRONG>0</STRONG></TD></TR>
192  </TABLE>
193</CENTER>
194<CENTER>
195  <TABLE COLS=6 WIDTH="60%" BORDER=2>
196<TR><TD ALIGN=center COLSPAN=2>Class</TD>
197    <TD ALIGN=center COLSPAN=2>Node</TD>
198    <TD ALIGN=center COLSPAN=2>Index</TD></TD>
199  </TABLE>
200</CENTER>
201@end html
202@end ifset
203
204The most significant six bits are the object class.  The next
205ten bits are the number of the node on which this object was
206created.  The node number is always one (1) in a single
207processor system.  The least significant sixteen bits form an
208identifier within a particular object type.  This identifier,
209called the object index, ranges in value from 1 to the maximum
210number of objects configured for this object type.
211
212
213The three components of an object ID make it possible
214to quickly locate any object in even the most complicated
215multiprocessor system.  Object ID's are associated with an
216object by RTEMS when the object is created and the corresponding
217ID is returned by the appropriate object create directive.  The
218object ID is required as input to all directives involving
219objects, except those which create an object or obtain the ID of
220an object.
221
222The object identification directives can be used to
223dynamically obtain a particular object's ID given its name.
224This mapping is accomplished by searching the name table
225associated with this object type.  If the name is non-unique,
226then the ID associated with the first occurrence of the name
227will be returned to the application.  Since object IDs are
228returned when the object is created, the object identification
229directives are not necessary in a properly designed single
230processor application.
231
232In addition, services are provided to portably examine the
233subcomponents of an RTEMS ID.  These services are
234described in detail later in this manual but are prototyped
235as follows:
236
237@cindex obtaining class from object ID
238@cindex obtaining node from object ID
239@cindex obtaining index from object ID
240@cindex get class from object ID
241@cindex get node from object ID
242@cindex get index from object ID
243@findex rtems_object_id_get_api
244@findex rtems_object_id_get_class
245@findex rtems_object_id_get_node
246@findex rtems_object_id_get_index
247
248@example
249uint32_t rtems_object_id_get_api( rtems_id );
250uint32_t rtems_object_id_get_class( rtems_id );
251uint32_t rtems_object_id_get_node( rtems_id );
252uint32_t rtems_object_id_get_index( rtems_id );
253@end example
254
255An object control block is a data structure defined
256by RTEMS which contains the information necessary to manage a
257particular object type.  For efficiency reasons, the format of
258each object type's control block is different.  However, many of
259the fields are similar in function.  The number of each type of
260control block is application dependent and determined by the
261values specified in the user's Configuration Table.  An object
262control block is allocated at object create time and freed when
263the object is deleted.  With the exception of user extension
264routines, object control blocks are not directly manipulated by
265user applications.
266
267@section Communication and Synchronization
268
269@cindex communication and synchronization
270
271In real-time multitasking applications, the ability
272for cooperating execution threads to communicate and synchronize
273with each other is imperative.  A real-time executive should
274provide an application with the following capabilities:
275
276@itemize @bullet
277@item Data transfer between cooperating tasks
278@item Data transfer between tasks and ISRs
279@item Synchronization of cooperating tasks
280@item Synchronization of tasks and ISRs
281@end itemize
282
283Most RTEMS managers can be used to provide some form
284of communication and/or synchronization.  However, managers
285dedicated specifically to communication and synchronization
286provide well established mechanisms which directly map to the
287application's varying needs.  This level of flexibility allows
288the application designer to match the features of a particular
289manager with the complexity of communication and synchronization
290required.  The following managers were specifically designed for
291communication and synchronization:
292
293@itemize @bullet
294@item Semaphore
295@item Message Queue
296@item Event
297@item Signal
298@end itemize
299
300The semaphore manager supports mutual exclusion
301involving the synchronization of access to one or more shared
302user resources.  Binary semaphores may utilize the optional
303priority inheritance algorithm to avoid the problem of priority
304inversion.  The message manager supports both communication and
305synchronization, while the event manager primarily provides a
306high performance synchronization mechanism.  The signal manager
307supports only asynchronous communication and is typically used
308for exception handling.
309
310@section Time
311
312@cindex time
313
314The development of responsive real-time applications
315requires an understanding of how RTEMS maintains and supports
316time-related operations.  The basic unit of time in RTEMS is
317known as a tick.  The frequency of clock ticks is completely
318application dependent and determines the granularity and
319accuracy of all interval and calendar time operations.
320
321@findex rtems_interval
322
323By tracking time in units of ticks, RTEMS is capable
324of supporting interval timing functions such as task delays,
325timeouts, timeslicing, the delayed execution of timer service
326routines, and the rate monotonic scheduling of tasks.  An
327interval is defined as a number of ticks relative to the current
328time.  For example, when a task delays for an interval of ten
329ticks, it is implied that the task will not execute until ten
330clock ticks have occurred.
331All intervals are specified using data type
332@code{@value{DIRPREFIX}interval}.
333
334A characteristic of interval timing is that the
335actual interval period may be a fraction of a tick less than the
336interval requested.  This occurs because the time at which the
337delay timer is set up occurs at some time between two clock
338ticks.  Therefore, the first countdown tick occurs in less than
339the complete time interval for a tick.  This can be a problem if
340the clock granularity is large.
341
342The rate monotonic scheduling algorithm is a hard
343real-time scheduling methodology.  This methodology provides
344rules which allows one to guarantee that a set of independent
345periodic tasks will always meet their deadlines -- even under
346transient overload conditions.  The rate monotonic manager
347provides directives built upon the Clock Manager's interval
348timer support routines.
349
350Interval timing is not sufficient for the many
351applications which require that time be kept in wall time or
352true calendar form.  Consequently, RTEMS maintains the current
353date and time.  This allows selected time operations to be
354scheduled at an actual calendar date and time.  For example, a
355task could request to delay until midnight on New Year's Eve
356before lowering the ball at Times Square.
357The data type @code{@value{DIRPREFIX}time_of_day} is used to specify
358calendar time in RTEMS services. 
359@xref{Clock Manager Time and Date Data Structures, , Time and Date Data Structures}.
360@findex rtems_time_of_day
361
362Obviously, the directives which use intervals or wall
363time cannot operate without some external mechanism which
364provides a periodic clock tick.  This clock tick is typically
365provided by a real time clock or counter/timer device.
366
367@section Memory Management
368
369@cindex memory management
370
371RTEMS memory management facilities can be grouped
372into two classes: dynamic memory allocation and address
373translation.  Dynamic memory allocation is required by
374applications whose memory requirements vary through the
375application's course of execution.  Address translation is
376needed by applications which share memory with another CPU or an
377intelligent Input/Output processor.  The following RTEMS
378managers provide facilities to manage memory:
379
380@itemize @bullet
381@item Region
382
383@item Partition
384
385@item Dual Ported Memory
386@end itemize
387
388RTEMS memory management features allow an application
389to create simple memory pools of fixed size buffers and/or more
390complex memory pools of variable size segments.  The partition
391manager provides directives to manage and maintain pools of
392fixed size entities such as resource control blocks.
393Alternatively, the region manager provides a more general
394purpose memory allocation scheme that supports variable size
395blocks of memory which are dynamically obtained and freed by the
396application.  The dual-ported memory manager provides executive
397support for address translation between internal and external
398dual-ported RAM address space.
Note: See TracBrowser for help on using the repository browser.