source: rtems/doc/user/concepts.t @ 2bf21fc8

4.104.11
Last change on this file since 2bf21fc8 was 2bf21fc8, checked in by Joel Sherrill <joel.sherrill@…>, on Dec 1, 2008 at 4:07:40 PM

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

  • ada_user/Makefile.am, user/Makefile.am, user/concepts.t: Add 16 bit object Id format information.
  • user/ObjectId-16Bits.eps, user/ObjectId-16Bits.png: New files.
  • Property mode set to 100644
File size: 14.3 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 integer value which uniquely identifies
122an object instance.  Object IDs are passed as arguments to many directives
123in RTEMS and RTEMS translates the ID to an internal object pointer. The
124efficient manipulation of object IDs is critical to the performance
125of RTEMS services.  Because of this, there are two object Id formats
126defined.  Each target architecture specifies which format it will use.
127There is a thirty-two bit format which is used for most of the supported
128architectures and supports multiprocessor configurations.  There is also
129a simpler sixteen bit format which is appropriate for smaller target
130architectures and does not support multiprocessor configurations.
131
132@subsubsection Thirty-Two Object ID Format
133
134The thirty-two bit format for an object ID is composed of four parts: API,
135object class, node, and index.  The data type @code{@value{DIRPREFIX}id}
136is used to store object IDs.
137
138
139@ifset use-ascii
140@example
141@group
142     31      27 26   24 23          16 15                             0
143     +---------+-------+--------------+-------------------------------+
144     |         |       |              |                               |
145     |  Class  |  API  |     Node     |             Index             |
146     |         |       |              |                               |
147     +---------+-------+--------------+-------------------------------+
148@end group
149@end example
150@end ifset
151
152@ifset use-tex
153@sp1
154@center{@image{ObjectId-32Bits,,2in}}
155@end ifset
156
157@ifset use-html
158@html
159<P ALIGN="center"><IMG SRC="ObjectId-32Bits.png"
160     WIDTH=550 HEIGHT=400 ALT="32 Bit Object Id"></P>
161@end html
162@end ifset
163
164The most significant five bits are the object class.  The next
165three bits indicate the API to which the object class belongs.
166The next eight bits (16-23) are the number of the node on which
167this object was created.  The node number is always one (1) in a single
168processor system.  The least significant sixteen bits form an
169identifier within a particular object type.  This identifier,
170called the object index, ranges in value from 1 to the maximum
171number of objects configured for this object type.
172
173@subsubsection Sixteen Bit Object ID Format
174
175The sixteen bit format for an object ID is composed of three parts: API,
176object class, and index.  The data type @code{@value{DIRPREFIX}id}
177is used to store object IDs.
178
179
180@ifset use-ascii
181@example
182@group
183     15      11 10    8 7            0
184     +---------+-------+--------------+
185     |         |       |              |
186     |  Class  |  API  |    Index     |
187     |         |       |              |
188     +---------+-------+--------------+
189@end group
190@end example
191@end ifset
192
193@ifset use-tex
194@sp1
195@center{@image{ObjectId-16Bits,,2in}}
196@end ifset
197
198@ifset use-html
199@html
200<P ALIGN="center"><IMG SRC="ObjectId-16Bits.png"
201     WIDTH=550 HEIGHT=400 ALT="16 Bit Object Id"></P>
202@end html
203@end ifset
204
205The sixteen-bit format is designed to be as similar as possible to the
206thrity-two bit format.  The differences are limited to the eliminatation
207of the node field and reduction of the index field from sixteen-bits
208to 8-bits.  Thus the sixteen bit format only supports up to 255 object
209instances per API/Class combination and single processor systems.
210As this format is typically utilized by sixteen-bit processors with
211limited address space, this is more than enough object instances.
212
213@subsection Object ID Description
214
215The components of an object ID make it possible
216to quickly locate any object in even the most complicated
217multiprocessor system.  Object ID's are associated with an
218object by RTEMS when the object is created and the corresponding
219ID is returned by the appropriate object create directive.  The
220object ID is required as input to all directives involving
221objects, except those which create an object or obtain the ID of
222an object.
223
224The object identification directives can be used to
225dynamically obtain a particular object's ID given its name.
226This mapping is accomplished by searching the name table
227associated with this object type.  If the name is non-unique,
228then the ID associated with the first occurrence of the name
229will be returned to the application.  Since object IDs are
230returned when the object is created, the object identification
231directives are not necessary in a properly designed single
232processor application.
233
234In addition, services are provided to portably examine the
235subcomponents of an RTEMS ID.  These services are
236described in detail later in this manual but are prototyped
237as follows:
238
239@cindex obtaining class from object ID
240@cindex obtaining node from object ID
241@cindex obtaining index from object ID
242@cindex get class from object ID
243@cindex get node from object ID
244@cindex get index from object ID
245@findex rtems_object_id_get_api
246@findex rtems_object_id_get_class
247@findex rtems_object_id_get_node
248@findex rtems_object_id_get_index
249
250@example
251uint32_t rtems_object_id_get_api( rtems_id );
252uint32_t rtems_object_id_get_class( rtems_id );
253uint32_t rtems_object_id_get_node( rtems_id );
254uint32_t rtems_object_id_get_index( rtems_id );
255@end example
256
257An object control block is a data structure defined
258by RTEMS which contains the information necessary to manage a
259particular object type.  For efficiency reasons, the format of
260each object type's control block is different.  However, many of
261the fields are similar in function.  The number of each type of
262control block is application dependent and determined by the
263values specified in the user's Configuration Table.  An object
264control block is allocated at object create time and freed when
265the object is deleted.  With the exception of user extension
266routines, object control blocks are not directly manipulated by
267user applications.
268
269@section Communication and Synchronization
270
271@cindex communication and synchronization
272
273In real-time multitasking applications, the ability
274for cooperating execution threads to communicate and synchronize
275with each other is imperative.  A real-time executive should
276provide an application with the following capabilities:
277
278@itemize @bullet
279@item Data transfer between cooperating tasks
280@item Data transfer between tasks and ISRs
281@item Synchronization of cooperating tasks
282@item Synchronization of tasks and ISRs
283@end itemize
284
285Most RTEMS managers can be used to provide some form
286of communication and/or synchronization.  However, managers
287dedicated specifically to communication and synchronization
288provide well established mechanisms which directly map to the
289application's varying needs.  This level of flexibility allows
290the application designer to match the features of a particular
291manager with the complexity of communication and synchronization
292required.  The following managers were specifically designed for
293communication and synchronization:
294
295@itemize @bullet
296@item Semaphore
297@item Message Queue
298@item Event
299@item Signal
300@end itemize
301
302The semaphore manager supports mutual exclusion
303involving the synchronization of access to one or more shared
304user resources.  Binary semaphores may utilize the optional
305priority inheritance algorithm to avoid the problem of priority
306inversion.  The message manager supports both communication and
307synchronization, while the event manager primarily provides a
308high performance synchronization mechanism.  The signal manager
309supports only asynchronous communication and is typically used
310for exception handling.
311
312@section Time
313
314@cindex time
315
316The development of responsive real-time applications
317requires an understanding of how RTEMS maintains and supports
318time-related operations.  The basic unit of time in RTEMS is
319known as a tick.  The frequency of clock ticks is completely
320application dependent and determines the granularity and
321accuracy of all interval and calendar time operations.
322
323@findex rtems_interval
324
325By tracking time in units of ticks, RTEMS is capable
326of supporting interval timing functions such as task delays,
327timeouts, timeslicing, the delayed execution of timer service
328routines, and the rate monotonic scheduling of tasks.  An
329interval is defined as a number of ticks relative to the current
330time.  For example, when a task delays for an interval of ten
331ticks, it is implied that the task will not execute until ten
332clock ticks have occurred.
333All intervals are specified using data type
334@code{@value{DIRPREFIX}interval}.
335
336A characteristic of interval timing is that the
337actual interval period may be a fraction of a tick less than the
338interval requested.  This occurs because the time at which the
339delay timer is set up occurs at some time between two clock
340ticks.  Therefore, the first countdown tick occurs in less than
341the complete time interval for a tick.  This can be a problem if
342the clock granularity is large.
343
344The rate monotonic scheduling algorithm is a hard
345real-time scheduling methodology.  This methodology provides
346rules which allows one to guarantee that a set of independent
347periodic tasks will always meet their deadlines -- even under
348transient overload conditions.  The rate monotonic manager
349provides directives built upon the Clock Manager's interval
350timer support routines.
351
352Interval timing is not sufficient for the many
353applications which require that time be kept in wall time or
354true calendar form.  Consequently, RTEMS maintains the current
355date and time.  This allows selected time operations to be
356scheduled at an actual calendar date and time.  For example, a
357task could request to delay until midnight on New Year's Eve
358before lowering the ball at Times Square.
359The data type @code{@value{DIRPREFIX}time_of_day} is used to specify
360calendar time in RTEMS services. 
361@xref{Clock Manager Time and Date Data Structures, , Time and Date Data Structures}.
362@findex rtems_time_of_day
363
364Obviously, the directives which use intervals or wall
365time cannot operate without some external mechanism which
366provides a periodic clock tick.  This clock tick is typically
367provided by a real time clock or counter/timer device.
368
369@section Memory Management
370
371@cindex memory management
372
373RTEMS memory management facilities can be grouped
374into two classes: dynamic memory allocation and address
375translation.  Dynamic memory allocation is required by
376applications whose memory requirements vary through the
377application's course of execution.  Address translation is
378needed by applications which share memory with another CPU or an
379intelligent Input/Output processor.  The following RTEMS
380managers provide facilities to manage memory:
381
382@itemize @bullet
383@item Region
384
385@item Partition
386
387@item Dual Ported Memory
388@end itemize
389
390RTEMS memory management features allow an application
391to create simple memory pools of fixed size buffers and/or more
392complex memory pools of variable size segments.  The partition
393manager provides directives to manage and maintain pools of
394fixed size entities such as resource control blocks.
395Alternatively, the region manager provides a more general
396purpose memory allocation scheme that supports variable size
397blocks of memory which are dynamically obtained and freed by the
398application.  The dual-ported memory manager provides executive
399support for address translation between internal and external
400dual-ported RAM address space.
Note: See TracBrowser for help on using the repository browser.