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

Last change on this file since bd861cc6 was bd861cc6, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 9, 2009 at 2:36:14 PM

2009-11-09 Joel Sherrill <joel.sherrill@…>

  • ada_user/, ada_user/ada_user.texi, user/, user/c_user.texi, user/concepts.t, user/overview.t, user/preface.texi, user/schedule.t, user/sem.t: Add table of figures. Add text and graphic of tree illustrating valid combinations of semaphore attributes.
  • user/semaphore_attributes.eps, user/semaphore_attributes.png: New files.
  • Property mode set to 100644
File size: 14.5 KB
2@c  COPYRIGHT (c) 1988-2007.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
6@c  $Id$
10@c  The following figure was replaced with an ASCII equivalent.
11@c    Figure 2-1 Object ID Composition
14@chapter Key Concepts
16@section Introduction
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.
24@section Objects
26@cindex objects
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.
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.
46@subsection Object Names
48@cindex object name
49@findex rtems_object_name
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.
55@findex rtems_build_name
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:
64@ifset is-C
66rtems_object_name my_name;
68my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
69@end example
70@end ifset
72@ifset is-Ada
74My_Name : RTEMS.Name;
76My_Name = RTEMS.Build_Name( 'L', 'I', 'T', 'E' );
77@end example
78@end ifset
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.
87@ifset is-C
88@findex rtems_object_get_name
90RTEMS provides a helper routine, @code{@value{DIRPREFIX}object_get_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.
94The following example illustrates the use of this method to print
95an object name:
98#include <rtems.h>
99#include <rtems/bspIo.h>
101void print_name(rtems_id the_object)
103  char  buffer[10];   /* name assumed to be 10 characters or less */
104  char *result;
106  result = rtems_object_get_name( id, sizeof(buffer), buffer );
107  printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
109@end example
110@end ifset
113@subsection Object IDs
115@cindex object ID
116@cindex object ID composition
117@findex rtems_id
119@need 3000
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.
132@subsubsection Thirty-Two Object ID Format
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.
139@float Figure,fig:Object-Id-32
140@caption{Thirty-Two Bit Object Id}
142@ifset use-ascii
145     31      27 26   24 23          16 15                             0
146     +---------+-------+--------------+-------------------------------+
147     |         |       |              |                               |
148     |  Class  |  API  |     Node     |             Index             |
149     |         |       |              |                               |
150     +---------+-------+--------------+-------------------------------+
151@end group
152@end example
153@end ifset
155@ifset use-tex
157@center{@image{ObjectId-32Bits,,2in,Thirty-Two Bit Object Id}}
158@end ifset
160@ifset use-html
162<P ALIGN="center"><IMG SRC="ObjectId-32Bits.png"
163     WIDTH=550 HEIGHT=400 ALT="Thirty-Two Bit Object Id"></P>
164@end html
165@end ifset
166@end float
168The most significant five bits are the object class.  The next
169three bits indicate the API to which the object class belongs.
170The next eight bits (16-23) are the number of the node on which
171this object was created.  The node number is always one (1) in a single
172processor system.  The least significant sixteen bits form an
173identifier within a particular object type.  This identifier,
174called the object index, ranges in value from 1 to the maximum
175number of objects configured for this object type.
177@subsubsection Sixteen Bit Object ID Format
179The sixteen bit format for an object ID is composed of three parts: API,
180object class, and index.  The data type @code{@value{DIRPREFIX}id}
181is used to store object IDs.
183@float Figure,fig:Object-Id-16
184@caption{Sixteen Bit Object Id}
187@ifset use-ascii
190     15      11 10    8 7            0
191     +---------+-------+--------------+
192     |         |       |              |
193     |  Class  |  API  |    Index     |
194     |         |       |              |
195     +---------+-------+--------------+
196@end group
197@end example
198@end ifset
200@ifset use-tex
202@center{@image{ObjectId-16Bits,,2in,Sixteen Bit Object Id}}
203@end ifset
205@ifset use-html
207<P ALIGN="center"><IMG SRC="ObjectId-16Bits.png"
208     WIDTH=550 HEIGHT=400 ALT="16 Bit Object Id"></P>
209@end html
210@end ifset
211@end float
213The sixteen-bit format is designed to be as similar as possible to the
214thrity-two bit format.  The differences are limited to the eliminatation
215of the node field and reduction of the index field from sixteen-bits
216to 8-bits.  Thus the sixteen bit format only supports up to 255 object
217instances per API/Class combination and single processor systems.
218As this format is typically utilized by sixteen-bit processors with
219limited address space, this is more than enough object instances.
221@subsection Object ID Description
223The components of an object ID make it possible
224to quickly locate any object in even the most complicated
225multiprocessor system.  Object ID's are associated with an
226object by RTEMS when the object is created and the corresponding
227ID is returned by the appropriate object create directive.  The
228object ID is required as input to all directives involving
229objects, except those which create an object or obtain the ID of
230an object.
232The object identification directives can be used to
233dynamically obtain a particular object's ID given its name.
234This mapping is accomplished by searching the name table
235associated with this object type.  If the name is non-unique,
236then the ID associated with the first occurrence of the name
237will be returned to the application.  Since object IDs are
238returned when the object is created, the object identification
239directives are not necessary in a properly designed single
240processor application.
242In addition, services are provided to portably examine the
243subcomponents of an RTEMS ID.  These services are
244described in detail later in this manual but are prototyped
245as follows:
247@cindex obtaining class from object ID
248@cindex obtaining node from object ID
249@cindex obtaining index from object ID
250@cindex get class from object ID
251@cindex get node from object ID
252@cindex get index from object ID
253@findex rtems_object_id_get_api
254@findex rtems_object_id_get_class
255@findex rtems_object_id_get_node
256@findex rtems_object_id_get_index
259uint32_t rtems_object_id_get_api( rtems_id );
260uint32_t rtems_object_id_get_class( rtems_id );
261uint32_t rtems_object_id_get_node( rtems_id );
262uint32_t rtems_object_id_get_index( rtems_id );
263@end example
265An object control block is a data structure defined
266by RTEMS which contains the information necessary to manage a
267particular object type.  For efficiency reasons, the format of
268each object type's control block is different.  However, many of
269the fields are similar in function.  The number of each type of
270control block is application dependent and determined by the
271values specified in the user's Configuration Table.  An object
272control block is allocated at object create time and freed when
273the object is deleted.  With the exception of user extension
274routines, object control blocks are not directly manipulated by
275user applications.
277@section Communication and Synchronization
279@cindex communication and synchronization
281In real-time multitasking applications, the ability
282for cooperating execution threads to communicate and synchronize
283with each other is imperative.  A real-time executive should
284provide an application with the following capabilities:
286@itemize @bullet
287@item Data transfer between cooperating tasks
288@item Data transfer between tasks and ISRs
289@item Synchronization of cooperating tasks
290@item Synchronization of tasks and ISRs
291@end itemize
293Most RTEMS managers can be used to provide some form
294of communication and/or synchronization.  However, managers
295dedicated specifically to communication and synchronization
296provide well established mechanisms which directly map to the
297application's varying needs.  This level of flexibility allows
298the application designer to match the features of a particular
299manager with the complexity of communication and synchronization
300required.  The following managers were specifically designed for
301communication and synchronization:
303@itemize @bullet
304@item Semaphore
305@item Message Queue
306@item Event
307@item Signal
308@end itemize
310The semaphore manager supports mutual exclusion
311involving the synchronization of access to one or more shared
312user resources.  Binary semaphores may utilize the optional
313priority inheritance algorithm to avoid the problem of priority
314inversion.  The message manager supports both communication and
315synchronization, while the event manager primarily provides a
316high performance synchronization mechanism.  The signal manager
317supports only asynchronous communication and is typically used
318for exception handling.
320@section Time
322@cindex time
324The development of responsive real-time applications
325requires an understanding of how RTEMS maintains and supports
326time-related operations.  The basic unit of time in RTEMS is
327known as a tick.  The frequency of clock ticks is completely
328application dependent and determines the granularity and
329accuracy of all interval and calendar time operations.
331@findex rtems_interval
333By tracking time in units of ticks, RTEMS is capable
334of supporting interval timing functions such as task delays,
335timeouts, timeslicing, the delayed execution of timer service
336routines, and the rate monotonic scheduling of tasks.  An
337interval is defined as a number of ticks relative to the current
338time.  For example, when a task delays for an interval of ten
339ticks, it is implied that the task will not execute until ten
340clock ticks have occurred.
341All intervals are specified using data type
344A characteristic of interval timing is that the
345actual interval period may be a fraction of a tick less than the
346interval requested.  This occurs because the time at which the
347delay timer is set up occurs at some time between two clock
348ticks.  Therefore, the first countdown tick occurs in less than
349the complete time interval for a tick.  This can be a problem if
350the clock granularity is large.
352The rate monotonic scheduling algorithm is a hard
353real-time scheduling methodology.  This methodology provides
354rules which allows one to guarantee that a set of independent
355periodic tasks will always meet their deadlines -- even under
356transient overload conditions.  The rate monotonic manager
357provides directives built upon the Clock Manager's interval
358timer support routines.
360Interval timing is not sufficient for the many
361applications which require that time be kept in wall time or
362true calendar form.  Consequently, RTEMS maintains the current
363date and time.  This allows selected time operations to be
364scheduled at an actual calendar date and time.  For example, a
365task could request to delay until midnight on New Year's Eve
366before lowering the ball at Times Square.
367The data type @code{@value{DIRPREFIX}time_of_day} is used to specify
368calendar time in RTEMS services. 
369@xref{Clock Manager Time and Date Data Structures, , Time and Date Data Structures}.
370@findex rtems_time_of_day
372Obviously, the directives which use intervals or wall
373time cannot operate without some external mechanism which
374provides a periodic clock tick.  This clock tick is typically
375provided by a real time clock or counter/timer device.
377@section Memory Management
379@cindex memory management
381RTEMS memory management facilities can be grouped
382into two classes: dynamic memory allocation and address
383translation.  Dynamic memory allocation is required by
384applications whose memory requirements vary through the
385application's course of execution.  Address translation is
386needed by applications which share memory with another CPU or an
387intelligent Input/Output processor.  The following RTEMS
388managers provide facilities to manage memory:
390@itemize @bullet
391@item Region
393@item Partition
395@item Dual Ported Memory
396@end itemize
398RTEMS memory management features allow an application
399to create simple memory pools of fixed size buffers and/or more
400complex memory pools of variable size segments.  The partition
401manager provides directives to manage and maintain pools of
402fixed size entities such as resource control blocks.
403Alternatively, the region manager provides a more general
404purpose memory allocation scheme that supports variable size
405blocks of memory which are dynamically obtained and freed by the
406application.  The dual-ported memory manager provides executive
407support for address translation between internal and external
408dual-ported RAM address space.
Note: See TracBrowser for help on using the repository browser.