source: rtems-docs/c_user/key_concepts.rst @ 9aafb39

Last change on this file since 9aafb39 was 9aafb39, checked in by Chris Johns <chrisj@…>, on Oct 28, 2016 at 12:56:02 PM

c_user: Remove errors and warnings.

  • Property mode set to 100644
File size: 13.4 KB
[489740f]1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
[b8d3f6b]3.. COMMENT: COPYRIGHT (c) 1988-2008.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
[fd6dc8c]7Key Concepts
[b8d3f6b]13The facilities provided by RTEMS are built upon a foundation of very powerful
14concepts.  These concepts must be understood before the application developer
15can efficiently utilize RTEMS.  The purpose of this chapter is to familiarize
[fd6dc8c]16one with these concepts.
[b8d3f6b]18.. _objects:
23.. index:: objects
[b8d3f6b]25RTEMS provides directives which can be used to dynamically create, delete, and
26manipulate a set of predefined object types.  These types include tasks,
27message queues, semaphores, memory regions, memory partitions, timers, ports,
28and rate monotonic periods.  The object-oriented nature of RTEMS encourages the
29creation of modular applications built upon re-usable "building block"
32All objects are created on the local node as required by the application and
33have an RTEMS assigned ID.  All objects have a user-assigned name.  Although a
34relationship exists between an object's name and its RTEMS assigned ID, the
35name and ID are not identical.  Object names are completely arbitrary and
36selected by the user as a meaningful "tag" which may commonly reflect the
37object's use in the application.  Conversely, object IDs are designed to
38facilitate efficient object manipulation by the executive.
40Object Names
42.. index:: object name
[080608f]43.. index:: rtems_name
[b8d3f6b]45An object name is an unsigned thirty-two bit entity associated with the object
46by the user.  The data type ``rtems_name`` is used to store object
47names... index:: rtems_build_name
49Although not required by RTEMS, object names are often composed of four ASCII
50characters which help identify that object.  For example, a task which causes a
51light to blink might be called "LITE".  The ``rtems_build_name`` routine is
52provided to build an object name from four ASCII characters.  The following
[f02e872]53example illustrates this:
[25d55d4]55.. code-block:: c
[080608f]57    rtems_name my_name;
[fd6dc8c]58    my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
[b8d3f6b]60However, it is not required that the application use ASCII characters to build
61object names.  For example, if an application requires one-hundred tasks, it
62would be difficult to assign meaningful ASCII names to each task.  A more
63convenient approach would be to name them the binary values one through
[f02e872]64one-hundred, respectively.
66.. index:: rtems_object_get_name
[b8d3f6b]68RTEMS provides a helper routine, ``rtems_object_get_name``, which can be used
69to obtain the name of any RTEMS object using just its ID.  This routine
70attempts to convert the name into a printable string.
72The following example illustrates the use of this method to print an object
[25d55d4]75.. code-block:: c
77    #include <rtems.h>
78    #include <rtems/bspIo.h>
79    void print_name(rtems_id id)
80    {
[b8d3f6b]81        char  buffer[10];   /* name assumed to be 10 characters or less */
82        char *result;
83        result = rtems_object_get_name( id, sizeof(buffer), buffer );
84        printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
[fd6dc8c]85    }
87Object IDs
89.. index:: object ID
90.. index:: object ID composition
91.. index:: rtems_id
[b8d3f6b]93An object ID is a unique unsigned integer value which uniquely identifies an
94object instance.  Object IDs are passed as arguments to many directives in
95RTEMS and RTEMS translates the ID to an internal object pointer. The efficient
96manipulation of object IDs is critical to the performance of RTEMS services.
97Because of this, there are two object Id formats defined.  Each target
98architecture specifies which format it will use.  There is a thirty-two bit
99format which is used for most of the supported architectures and supports
100multiprocessor configurations.  There is also a simpler sixteen bit format
101which is appropriate for smaller target architectures and does not support
102multiprocessor configurations.
104Thirty-Two Object ID Format
107The thirty-two bit format for an object ID is composed of four parts: API,
[b8d3f6b]108object class, node, and index.  The data type ``rtems_id`` is used to store
109object IDs.
[25d55d4]111.. code-block:: c
113    31      27 26   24 23          16 15                             0
114    +---------+-------+--------------+-------------------------------+
115    |         |       |              |                               |
116    |  Class  |  API  |     Node     |             Index             |
117    |         |       |              |                               |
118    +---------+-------+--------------+-------------------------------+
[b8d3f6b]120The most significant five bits are the object class.  The next three bits
121indicate the API to which the object class belongs.  The next eight bits
122(16-23) are the number of the node on which this object was created.  The node
123number is always one (1) in a single processor system.  The least significant
124sixteen bits form an identifier within a particular object type.  This
125identifier, called the object index, ranges in value from 1 to the maximum
[fd6dc8c]126number of objects configured for this object type.
128Sixteen Bit Object ID Format
[b8d3f6b]131The sixteen bit format for an object ID is composed of three parts: API, object
132class, and index.  The data type ``rtems_id`` is used to store object IDs.
[25d55d4]134.. code-block:: c
136    15      11 10    8 7            0
137    +---------+-------+--------------+
138    |         |       |              |
139    |  Class  |  API  |    Index     |
140    |         |       |              |
141    +---------+-------+--------------+
143The sixteen-bit format is designed to be as similar as possible to the
[b8d3f6b]144thrity-two bit format.  The differences are limited to the eliminatation of the
145node field and reduction of the index field from sixteen-bits to 8-bits.  Thus
146the sixteen bit format only supports up to 255 object instances per API/Class
147combination and single processor systems.  As this format is typically utilized
148by sixteen-bit processors with limited address space, this is more than enough
149object instances.
151Object ID Description
[b8d3f6b]154The components of an object ID make it possible to quickly locate any object in
155even the most complicated multiprocessor system.  Object ID's are associated
156with an object by RTEMS when the object is created and the corresponding ID is
157returned by the appropriate object create directive.  The object ID is required
158as input to all directives involving objects, except those which create an
159object or obtain the ID of an object.
161The object identification directives can be used to dynamically obtain a
162particular object's ID given its name.  This mapping is accomplished by
163searching the name table associated with this object type.  If the name is
164non-unique, then the ID associated with the first occurrence of the name will
165be returned to the application.  Since object IDs are returned when the object
166is created, the object identification directives are not necessary in a
167properly designed single processor application.
169In addition, services are provided to portably examine the subcomponents of an
170RTEMS ID.  These services are described in detail later in this manual but are
[66220bc]171prototyped as follows:
[66220bc]173.. index:: obtaining class from object ID
[fd6dc8c]174.. index:: obtaining node from object ID
175.. index:: obtaining index from object ID
176.. index:: get class from object ID
177.. index:: get node from object ID
178.. index:: get index from object ID
179.. index:: rtems_object_id_get_api
180.. index:: rtems_object_id_get_class
181.. index:: rtems_object_id_get_node
182.. index:: rtems_object_id_get_index
[25d55d4]184.. code-block:: c
186    uint32_t rtems_object_id_get_api( rtems_id );
187    uint32_t rtems_object_id_get_class( rtems_id );
188    uint32_t rtems_object_id_get_node( rtems_id );
189    uint32_t rtems_object_id_get_index( rtems_id );
[b8d3f6b]191An object control block is a data structure defined by RTEMS which contains the
192information necessary to manage a particular object type.  For efficiency
193reasons, the format of each object type's control block is different.  However,
194many of the fields are similar in function.  The number of each type of control
195block is application dependent and determined by the values specified in the
196user's Configuration Table.  An object control block is allocated at object
197create time and freed when the object is deleted.  With the exception of user
198extension routines, object control blocks are not directly manipulated by user
201Communication and Synchronization
203.. index:: communication and synchronization
[b8d3f6b]205In real-time multitasking applications, the ability for cooperating execution
206threads to communicate and synchronize with each other is imperative.  A
207real-time executive should provide an application with the following
210- Data transfer between cooperating tasks
212- Data transfer between tasks and ISRs
214- Synchronization of cooperating tasks
216- Synchronization of tasks and ISRs
[b8d3f6b]218Most RTEMS managers can be used to provide some form of communication and/or
219synchronization.  However, managers dedicated specifically to communication and
220synchronization provide well established mechanisms which directly map to the
221application's varying needs.  This level of flexibility allows the application
222designer to match the features of a particular manager with the complexity of
223communication and synchronization required.  The following managers were
224specifically designed for communication and synchronization:
226- Semaphore
228- Message Queue
230- Event
232- Signal
[b8d3f6b]234The semaphore manager supports mutual exclusion involving the synchronization
235of access to one or more shared user resources.  Binary semaphores may utilize
236the optional priority inheritance algorithm to avoid the problem of priority
[fd6dc8c]237inversion.  The message manager supports both communication and
[b8d3f6b]238synchronization, while the event manager primarily provides a high performance
239synchronization mechanism.  The signal manager supports only asynchronous
240communication and is typically used for exception handling.
244.. index:: time
[b8d3f6b]246The development of responsive real-time applications requires an understanding
247of how RTEMS maintains and supports time-related operations.  The basic unit of
248time in RTEMS is known as a tick.  The frequency of clock ticks is completely
249application dependent and determines the granularity and accuracy of all
[c9aaf31]250interval and calendar time operations.
252.. index:: rtems_interval
254By tracking time in units of ticks, RTEMS is capable of supporting interval
255timing functions such as task delays, timeouts, timeslicing, the delayed
256execution of timer service routines, and the rate monotonic scheduling of
257tasks.  An interval is defined as a number of ticks relative to the current
258time.  For example, when a task delays for an interval of ten ticks, it is
259implied that the task will not execute until ten clock ticks have occurred.
260All intervals are specified using data type ``rtems_interval``.
262A characteristic of interval timing is that the actual interval period may be a
263fraction of a tick less than the interval requested.  This occurs because the
264time at which the delay timer is set up occurs at some time between two clock
265ticks.  Therefore, the first countdown tick occurs in less than the complete
266time interval for a tick.  This can be a problem if the clock granularity is
269The rate monotonic scheduling algorithm is a hard real-time scheduling
270methodology.  This methodology provides rules which allows one to guarantee
[1a72a98]271that a set of independent periodic tasks will always meet their deadlines even
272under transient overload conditions.  The rate monotonic manager provides
[b8d3f6b]273directives built upon the Clock Manager's interval timer support routines.
275Interval timing is not sufficient for the many applications which require that
276time be kept in wall time or true calendar form.  Consequently, RTEMS maintains
277the current date and time.  This allows selected time operations to be
278scheduled at an actual calendar date and time.  For example, a task could
279request to delay until midnight on New Year's Eve before lowering the ball at
280Times Square.  The data type ``rtems_time_of_day`` is used to specify calendar
[9aafb39]281time in RTEMS services.  See :ref:`Time and Date Data Structures`.
[1a72a98]283.. index:: rtems_time_of_day
[b8d3f6b]285Obviously, the directives which use intervals or wall time cannot operate
286without some external mechanism which provides a periodic clock tick.  This
287clock tick is typically provided by a real time clock or counter/timer device.
289Memory Management
291.. index:: memory management
[b8d3f6b]293RTEMS memory management facilities can be grouped into two classes: dynamic
294memory allocation and address translation.  Dynamic memory allocation is
295required by applications whose memory requirements vary through the
296application's course of execution.  Address translation is needed by
297applications which share memory with another CPU or an intelligent Input/Output
298processor.  The following RTEMS managers provide facilities to manage memory:
300- Region
302- Partition
304- Dual Ported Memory
[b8d3f6b]306RTEMS memory management features allow an application to create simple memory
307pools of fixed size buffers and/or more complex memory pools of variable size
308segments.  The partition manager provides directives to manage and maintain
309pools of fixed size entities such as resource control blocks.  Alternatively,
310the region manager provides a more general purpose memory allocation scheme
311that supports variable size blocks of memory which are dynamically obtained and
312freed by the application.  The dual-ported memory manager provides executive
313support for address translation between internal and external dual-ported RAM
314address space.
Note: See TracBrowser for help on using the repository browser.