source: rtems/doc/user/concepts.t @ 1a34b8c

4.104.115
Last change on this file since 1a34b8c was 1a34b8c, checked in by Joel Sherrill <joel.sherrill@…>, on 11/07/08 at 20:16:24

2008-11-07 Joel Sherrill <joel.sherrill@…>

  • user/concepts.t: Use 32 bit version centered.
  • Property mode set to 100644
File size: 12.3 KB
RevLine 
[ae68ff0]1@c
[4ffbc49]2@c  COPYRIGHT (c) 1988-2007.
[ae68ff0]3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
[139b2e4a]6@c  $Id$
7@c
[ae68ff0]8
9@c
10@c  The following figure was replaced with an ASCII equivalent.
11@c    Figure 2-1 Object ID Composition
12@c
[20515fc]13
[ae68ff0]14@chapter Key Concepts
[20515fc]15
[ae68ff0]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
[169502e]26@cindex objects
27
[ae68ff0]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
[adee5979]46@subsection Object Names
47
[169502e]48@cindex object name
[adee5979]49@findex rtems_object_name
[169502e]50
[ae68ff0]51An object name is an unsigned thirty-two bit entity
[adee5979]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
[4ffbc49]64@ifset is-C
[adee5979]65@example
66rtems_object_name my_name;
67
68my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
69@end example
70@end ifset
71
[4ffbc49]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
[ae68ff0]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
[4ffbc49]87@ifset is-C
[35a81f8]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
[adee5979]113@subsection Object IDs
114
[169502e]115@cindex object ID
[71689d44]116@cindex object ID composition
[adee5979]117@findex rtems_id
[169502e]118
[ae68ff0]119@need 3000
120
121An object ID is a unique unsigned thirty-two bit
[1fa78236]122entity composed of three parts: API, object class, node, and index.
[adee5979]123The data type @code{@value{DIRPREFIX}id} is used to store object IDs.
124
[ae68ff0]125
126@ifset use-ascii
127@example
128@group
[1fa78236]129     31      27 26   24 23          16 15                             0
130     +---------+-------+--------------+-------------------------------+
131     |         |       |              |                               |
132     |  Class  |  API  |     Node     |             Index             |
133     |         |       |              |                               |
134     +---------+-------+--------------+-------------------------------+
[ae68ff0]135@end group
136@end example
137@end ifset
138
139@ifset use-tex
[1fa78236]140@sp1
141@center{@image{ObjectId-32Bits,,2in}}
[ae68ff0]142@end ifset
143
144@ifset use-html
145@html
[1a34b8c]146<P ALIGN="center"><IMG SRC="ObjectId-32Bits.png"
147     WIDTH=550 HEIGHT=400 ALT="32 Bit Object Id"></P>
[ae68ff0]148@end html
149@end ifset
150
[1fa78236]151The most significant five bits are the object class.  The next
152three bits indicate the API to which the object class belongs.
153The next eight bits (16-23) are the number of the node on which
154this object was created.  The node number is always one (1) in a single
[71689d44]155processor system.  The least significant sixteen bits form an
156identifier within a particular object type.  This identifier,
157called the object index, ranges in value from 1 to the maximum
158number of objects configured for this object type.
159
[1fa78236]160The four components of an object ID make it possible
[ae68ff0]161to quickly locate any object in even the most complicated
162multiprocessor system.  Object ID's are associated with an
163object by RTEMS when the object is created and the corresponding
164ID is returned by the appropriate object create directive.  The
165object ID is required as input to all directives involving
166objects, except those which create an object or obtain the ID of
167an object.
168
169The object identification directives can be used to
170dynamically obtain a particular object's ID given its name.
171This mapping is accomplished by searching the name table
172associated with this object type.  If the name is non-unique,
173then the ID associated with the first occurrence of the name
174will be returned to the application.  Since object IDs are
175returned when the object is created, the object identification
176directives are not necessary in a properly designed single
177processor application.
178
[71689d44]179In addition, services are provided to portably examine the
[d5671b1]180subcomponents of an RTEMS ID.  These services are
181described in detail later in this manual but are prototyped
182as follows:
[71689d44]183
184@cindex obtaining class from object ID
185@cindex obtaining node from object ID
186@cindex obtaining index from object ID
187@cindex get class from object ID
188@cindex get node from object ID
189@cindex get index from object ID
[d5671b1]190@findex rtems_object_id_get_api
191@findex rtems_object_id_get_class
192@findex rtems_object_id_get_node
193@findex rtems_object_id_get_index
[71689d44]194
195@example
[d5671b1]196uint32_t rtems_object_id_get_api( rtems_id );
197uint32_t rtems_object_id_get_class( rtems_id );
198uint32_t rtems_object_id_get_node( rtems_id );
199uint32_t rtems_object_id_get_index( rtems_id );
[71689d44]200@end example
201
[ae68ff0]202An object control block is a data structure defined
203by RTEMS which contains the information necessary to manage a
204particular object type.  For efficiency reasons, the format of
205each object type's control block is different.  However, many of
206the fields are similar in function.  The number of each type of
207control block is application dependent and determined by the
208values specified in the user's Configuration Table.  An object
209control block is allocated at object create time and freed when
210the object is deleted.  With the exception of user extension
211routines, object control blocks are not directly manipulated by
212user applications.
213
214@section Communication and Synchronization
215
[169502e]216@cindex communication and synchronization
217
[ae68ff0]218In real-time multitasking applications, the ability
219for cooperating execution threads to communicate and synchronize
220with each other is imperative.  A real-time executive should
221provide an application with the following capabilities:
222
223@itemize @bullet
224@item Data transfer between cooperating tasks
225@item Data transfer between tasks and ISRs
226@item Synchronization of cooperating tasks
227@item Synchronization of tasks and ISRs
228@end itemize
229
230Most RTEMS managers can be used to provide some form
231of communication and/or synchronization.  However, managers
232dedicated specifically to communication and synchronization
233provide well established mechanisms which directly map to the
234application's varying needs.  This level of flexibility allows
235the application designer to match the features of a particular
236manager with the complexity of communication and synchronization
237required.  The following managers were specifically designed for
238communication and synchronization:
239
240@itemize @bullet
241@item Semaphore
242@item Message Queue
243@item Event
244@item Signal
245@end itemize
246
247The semaphore manager supports mutual exclusion
248involving the synchronization of access to one or more shared
249user resources.  Binary semaphores may utilize the optional
250priority inheritance algorithm to avoid the problem of priority
251inversion.  The message manager supports both communication and
252synchronization, while the event manager primarily provides a
253high performance synchronization mechanism.  The signal manager
254supports only asynchronous communication and is typically used
255for exception handling.
256
257@section Time
258
[169502e]259@cindex time
260
[ae68ff0]261The development of responsive real-time applications
262requires an understanding of how RTEMS maintains and supports
263time-related operations.  The basic unit of time in RTEMS is
264known as a tick.  The frequency of clock ticks is completely
265application dependent and determines the granularity and
266accuracy of all interval and calendar time operations.
267
[adee5979]268@findex rtems_interval
269
[ae68ff0]270By tracking time in units of ticks, RTEMS is capable
271of supporting interval timing functions such as task delays,
272timeouts, timeslicing, the delayed execution of timer service
273routines, and the rate monotonic scheduling of tasks.  An
274interval is defined as a number of ticks relative to the current
275time.  For example, when a task delays for an interval of ten
276ticks, it is implied that the task will not execute until ten
277clock ticks have occurred.
[adee5979]278All intervals are specified using data type
279@code{@value{DIRPREFIX}interval}.
[ae68ff0]280
281A characteristic of interval timing is that the
282actual interval period may be a fraction of a tick less than the
283interval requested.  This occurs because the time at which the
284delay timer is set up occurs at some time between two clock
285ticks.  Therefore, the first countdown tick occurs in less than
286the complete time interval for a tick.  This can be a problem if
287the clock granularity is large.
288
289The rate monotonic scheduling algorithm is a hard
290real-time scheduling methodology.  This methodology provides
291rules which allows one to guarantee that a set of independent
292periodic tasks will always meet their deadlines -- even under
293transient overload conditions.  The rate monotonic manager
294provides directives built upon the Clock Manager's interval
295timer support routines.
296
297Interval timing is not sufficient for the many
298applications which require that time be kept in wall time or
299true calendar form.  Consequently, RTEMS maintains the current
300date and time.  This allows selected time operations to be
301scheduled at an actual calendar date and time.  For example, a
302task could request to delay until midnight on New Year's Eve
303before lowering the ball at Times Square.
[adee5979]304The data type @code{@value{DIRPREFIX}time_of_day} is used to specify
305calendar time in RTEMS services. 
306@xref{Clock Manager Time and Date Data Structures, , Time and Date Data Structures}.
307@findex rtems_time_of_day
[ae68ff0]308
309Obviously, the directives which use intervals or wall
310time cannot operate without some external mechanism which
311provides a periodic clock tick.  This clock tick is typically
312provided by a real time clock or counter/timer device.
313
314@section Memory Management
315
[169502e]316@cindex memory management
317
[ae68ff0]318RTEMS memory management facilities can be grouped
319into two classes: dynamic memory allocation and address
320translation.  Dynamic memory allocation is required by
321applications whose memory requirements vary through the
322application's course of execution.  Address translation is
323needed by applications which share memory with another CPU or an
324intelligent Input/Output processor.  The following RTEMS
325managers provide facilities to manage memory:
326
327@itemize @bullet
328@item Region
329
330@item Partition
331
332@item Dual Ported Memory
333@end itemize
334
335RTEMS memory management features allow an application
336to create simple memory pools of fixed size buffers and/or more
337complex memory pools of variable size segments.  The partition
338manager provides directives to manage and maintain pools of
339fixed size entities such as resource control blocks.
340Alternatively, the region manager provides a more general
341purpose memory allocation scheme that supports variable size
342blocks of memory which are dynamically obtained and freed by the
343application.  The dual-ported memory manager provides executive
344support for address translation between internal and external
345dual-ported RAM address space.
Note: See TracBrowser for help on using the repository browser.