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