[489740f] | 1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
| 2 | |
---|
[b8d3f6b] | 3 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
| 4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
| 5 | .. COMMENT: All rights reserved. |
---|
| 6 | |
---|
[fd6dc8c8] | 7 | Key Concepts |
---|
| 8 | ############ |
---|
| 9 | |
---|
| 10 | Introduction |
---|
| 11 | ============ |
---|
| 12 | |
---|
[b8d3f6b] | 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 |
---|
[fd6dc8c8] | 16 | one with these concepts. |
---|
| 17 | |
---|
[b8d3f6b] | 18 | .. _objects: |
---|
| 19 | |
---|
[fd6dc8c8] | 20 | Objects |
---|
| 21 | ======= |
---|
| 22 | |
---|
| 23 | .. index:: objects |
---|
| 24 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 39 | |
---|
| 40 | Object Names |
---|
| 41 | ------------ |
---|
| 42 | .. index:: object name |
---|
[080608f] | 43 | .. index:: rtems_name |
---|
[fd6dc8c8] | 44 | |
---|
[b8d3f6b] | 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 |
---|
[f02e872] | 53 | example illustrates this: |
---|
[fd6dc8c8] | 54 | |
---|
[25d55d4] | 55 | .. code-block:: c |
---|
[fd6dc8c8] | 56 | |
---|
[080608f] | 57 | rtems_name my_name; |
---|
[fd6dc8c8] | 58 | my_name = rtems_build_name( 'L', 'I', 'T', 'E' ); |
---|
| 59 | |
---|
[b8d3f6b] | 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 |
---|
[f02e872] | 64 | one-hundred, respectively. |
---|
| 65 | |
---|
| 66 | .. index:: rtems_object_get_name |
---|
[fd6dc8c8] | 67 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 74 | |
---|
[25d55d4] | 75 | .. code-block:: c |
---|
[fd6dc8c8] | 76 | |
---|
| 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") ); |
---|
[fd6dc8c8] | 85 | } |
---|
| 86 | |
---|
| 87 | Object IDs |
---|
| 88 | ---------- |
---|
| 89 | .. index:: object ID |
---|
| 90 | .. index:: object ID composition |
---|
| 91 | .. index:: rtems_id |
---|
| 92 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 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, |
---|
[b8d3f6b] | 108 | object class, node, and index. The data type ``rtems_id`` is used to store |
---|
| 109 | object IDs. |
---|
[fd6dc8c8] | 110 | |
---|
[25d55d4] | 111 | .. code-block:: c |
---|
[fd6dc8c8] | 112 | |
---|
| 113 | 31 27 26 24 23 16 15 0 |
---|
| 114 | +---------+-------+--------------+-------------------------------+ |
---|
| 115 | | | | | | |
---|
| 116 | | Class | API | Node | Index | |
---|
| 117 | | | | | | |
---|
| 118 | +---------+-------+--------------+-------------------------------+ |
---|
| 119 | |
---|
[b8d3f6b] | 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 |
---|
[fd6dc8c8] | 126 | number of objects configured for this object type. |
---|
| 127 | |
---|
| 128 | Sixteen Bit Object ID Format |
---|
| 129 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
| 130 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 133 | |
---|
[25d55d4] | 134 | .. code-block:: c |
---|
[fd6dc8c8] | 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 |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 150 | |
---|
| 151 | Object ID Description |
---|
| 152 | --------------------- |
---|
| 153 | |
---|
[b8d3f6b] | 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 |
---|
[66220bc] | 171 | prototyped as follows: |
---|
[b8d3f6b] | 172 | |
---|
[66220bc] | 173 | .. index:: obtaining class from object ID |
---|
[fd6dc8c8] | 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 | |
---|
[25d55d4] | 184 | .. code-block:: c |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 200 | |
---|
| 201 | Communication and Synchronization |
---|
| 202 | ================================= |
---|
| 203 | .. index:: communication and synchronization |
---|
| 204 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 225 | |
---|
| 226 | - Semaphore |
---|
| 227 | |
---|
| 228 | - Message Queue |
---|
| 229 | |
---|
| 230 | - Event |
---|
| 231 | |
---|
| 232 | - Signal |
---|
| 233 | |
---|
[b8d3f6b] | 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 |
---|
[fd6dc8c8] | 237 | inversion. The message manager supports both communication and |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 241 | |
---|
| 242 | Time |
---|
| 243 | ==== |
---|
| 244 | .. index:: time |
---|
| 245 | |
---|
[b8d3f6b] | 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 |
---|
[c9aaf31] | 250 | interval and calendar time operations. |
---|
| 251 | |
---|
| 252 | .. index:: rtems_interval |
---|
[b8d3f6b] | 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 |
---|
[1a72a98] | 271 | that a set of independent periodic tasks will always meet their deadlines even |
---|
| 272 | under transient overload conditions. The rate monotonic manager provides |
---|
[b8d3f6b] | 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 |
---|
[9aafb39] | 281 | time in RTEMS services. See :ref:`Time and Date Data Structures`. |
---|
[fd6dc8c8] | 282 | |
---|
[1a72a98] | 283 | .. index:: rtems_time_of_day |
---|
[fd6dc8c8] | 284 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 288 | |
---|
| 289 | Memory Management |
---|
| 290 | ================= |
---|
| 291 | .. index:: memory management |
---|
| 292 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 299 | |
---|
| 300 | - Region |
---|
| 301 | |
---|
| 302 | - Partition |
---|
| 303 | |
---|
| 304 | - Dual Ported Memory |
---|
| 305 | |
---|
[b8d3f6b] | 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. |
---|