1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> |
---|
4 | |
---|
5 | Introduction |
---|
6 | ************ |
---|
7 | |
---|
8 | Overview |
---|
9 | ======== |
---|
10 | |
---|
11 | You are someone looking for a real-time operating system. This document |
---|
12 | |
---|
13 | - presents the basic features of RTEMS, so that you can decide if it is worth to |
---|
14 | look at, |
---|
15 | |
---|
16 | - gives you a :ref:`quick start <QuickStart>` to install all the tools |
---|
17 | necessary to work with RTEMS, and |
---|
18 | |
---|
19 | - helps you to build an example application on top of RTEMS. |
---|
20 | |
---|
21 | Features |
---|
22 | ======== |
---|
23 | |
---|
24 | The Real-Time Executive for Multiprocessor Systems (:ref:term:`RTEMS`) is a |
---|
25 | multi-threaded, single address-space, real-time operating system with no |
---|
26 | kernel-space/user-space separation. It is capable to operate in an |
---|
27 | :ref:term:`SMP` configuration providing a state of the art feature set. |
---|
28 | |
---|
29 | RTEMS is licensed under a |
---|
30 | `modified GPL 2.0 or later license with an exception for static linking <https://git.rtems.org/rtems/tree/LICENSE>`_ |
---|
31 | [#]_. It exposes no license requirements on application code. The third-party |
---|
32 | software used and distributed by RTEMS which may be linked to the application |
---|
33 | is licensed under permissive open source licenses. Everything necessary to |
---|
34 | build RTEMS applications is available as open source software. This makes you |
---|
35 | completely vendor independent. |
---|
36 | |
---|
37 | RTEMS provides the following basic feature set: |
---|
38 | |
---|
39 | - :ref:term:`APIs <API>` |
---|
40 | |
---|
41 | - :ref:term:`POSIX` with |
---|
42 | `pthreads <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html>`_ |
---|
43 | (enables a broad range of standard software to run on RTEMS) |
---|
44 | |
---|
45 | - `Classic <https://docs.rtems.org/branches/master/c-user.pdf>`_ |
---|
46 | |
---|
47 | - :ref:term:`C11` (including |
---|
48 | `thread <https://en.cppreference.com/w/c/thread>`_ support) |
---|
49 | |
---|
50 | - :ref:term:`C++11` (including |
---|
51 | `thread <https://en.cppreference.com/w/cpp/thread>`_ support) |
---|
52 | |
---|
53 | - Newlib and :ref:term:`GCC` internal |
---|
54 | |
---|
55 | - Programming languages |
---|
56 | |
---|
57 | - C/C++/OpenMP (RTEMS Source Builder, RSB) |
---|
58 | |
---|
59 | - Ada (RSB, ``--with-ada``) |
---|
60 | |
---|
61 | - Erlang |
---|
62 | |
---|
63 | - Fortran (RSB, ``--with-fortran``) |
---|
64 | |
---|
65 | - Python and MicroPython |
---|
66 | |
---|
67 | - Parallel languages |
---|
68 | |
---|
69 | - :ref:term:`EMB²` |
---|
70 | |
---|
71 | - Google Go [#]_ |
---|
72 | |
---|
73 | - :ref:term:`OpenMP` 4.5 |
---|
74 | |
---|
75 | - Thread synchronization and communication |
---|
76 | |
---|
77 | - Mutexes with and without locking protocols |
---|
78 | |
---|
79 | - Counting semaphores |
---|
80 | |
---|
81 | - Binary semaphores |
---|
82 | |
---|
83 | - Condition variables |
---|
84 | |
---|
85 | - Events |
---|
86 | |
---|
87 | - Message queues |
---|
88 | |
---|
89 | - Barriers |
---|
90 | |
---|
91 | - :ref:term:`Futex` (used by :ref:term:`OpenMP` barriers) |
---|
92 | |
---|
93 | - Epoch Based Reclamation (libbsd) |
---|
94 | |
---|
95 | - Locking protocols |
---|
96 | |
---|
97 | - Transitive Priority Inheritance |
---|
98 | |
---|
99 | - :ref:term:`OMIP` (SMP feature) |
---|
100 | |
---|
101 | - Priority Ceiling |
---|
102 | |
---|
103 | - :ref:term:`MrsP` (SMP feature) |
---|
104 | |
---|
105 | - Scalable timer and timeout support |
---|
106 | |
---|
107 | - Lock-free timestamps (FreeBSD timecounters) |
---|
108 | |
---|
109 | - Responsive interrupt management |
---|
110 | |
---|
111 | - C11/C++11 :ref:term:`TLS` [#]_ |
---|
112 | |
---|
113 | - Link-time configurable schedulers |
---|
114 | |
---|
115 | - Fixed-priority |
---|
116 | |
---|
117 | - Job-level fixed-priority (:ref:term:`EDF`) |
---|
118 | |
---|
119 | - Constant Bandwidth Server (experimental) |
---|
120 | |
---|
121 | - Clustered scheduling (SMP feature) |
---|
122 | |
---|
123 | - Flexible link-time configuration |
---|
124 | |
---|
125 | - Job-level fixed-priority scheduler (:ref:term:`EDF`) with support for |
---|
126 | one-to-one and one-to-all thread to processor affinities (default SMP |
---|
127 | scheduler) |
---|
128 | |
---|
129 | - Fixed-priority scheduler |
---|
130 | |
---|
131 | - Proof-of-concept strong :ref:term:`APA` scheduler |
---|
132 | |
---|
133 | - Focus on link-time application-specific configuration |
---|
134 | |
---|
135 | - Linker-set based initialization (similar to global C++ constructors) |
---|
136 | |
---|
137 | - Operating system uses fine-grained locking (SMP feature) |
---|
138 | |
---|
139 | - Dynamic memory allocators |
---|
140 | |
---|
141 | - First-fit (default) |
---|
142 | |
---|
143 | - Universal Memory Allocator |
---|
144 | (`UMA <https://www.freebsd.org/cgi/man.cgi?query=uma&sektion=9>`_ , |
---|
145 | libbsd) |
---|
146 | |
---|
147 | - File systems |
---|
148 | |
---|
149 | - :ref:term:`IMFS` |
---|
150 | |
---|
151 | - :ref:term:`FAT` |
---|
152 | |
---|
153 | - :ref:term:`RFS` |
---|
154 | |
---|
155 | - :ref:term:`NFSv2` |
---|
156 | |
---|
157 | - :ref:term:`JFFS2` (NOR flashes) |
---|
158 | |
---|
159 | - :ref:term:`YAFFS2` (NAND flashes, GPL or commercial license required) |
---|
160 | |
---|
161 | - Device drivers |
---|
162 | |
---|
163 | - Termios (serial interfaces) |
---|
164 | |
---|
165 | - I2C (Linux user-space API compatible) |
---|
166 | |
---|
167 | - SPI (Linux user-space API compatible) |
---|
168 | |
---|
169 | - Network stacks (legacy, libbsd, lwIP) |
---|
170 | |
---|
171 | - USB stack (libbsd) |
---|
172 | |
---|
173 | - SD/MMC card stack (libbsd) |
---|
174 | |
---|
175 | - Framebuffer (Linux user-space API compatible, Qt) |
---|
176 | |
---|
177 | - Application runs in kernel-space and can access hardware directly |
---|
178 | |
---|
179 | - libbsd |
---|
180 | |
---|
181 | - Port of FreeBSD user-space and kernel-space components to RTEMS |
---|
182 | |
---|
183 | - Easy access to FreeBSD software for RTEMS |
---|
184 | |
---|
185 | - Support to stay in synchronization with FreeBSD |
---|
186 | |
---|
187 | .. _ecosystem: |
---|
188 | |
---|
189 | Ecosystem |
---|
190 | ========= |
---|
191 | .. index:: Ecosystem |
---|
192 | |
---|
193 | The RTEMS Ecosystem is the collection of tools, packages, code, documentation |
---|
194 | and online content provided by the RTEMS Project. The ecosystem provides a way |
---|
195 | to develop, maintain, and use RTEMS. It's parts interact with the user, the |
---|
196 | host environment, and each other to make RTEMS accessible, useable and |
---|
197 | predicable. |
---|
198 | |
---|
199 | The ecosystem is for users, developers and maintainers and it is an ongoing |
---|
200 | effort that needs your help and support. The RTEMS project is always improving |
---|
201 | the way it delivers the kernel to you and your feedback is important so please |
---|
202 | join the mailing lists and contribute back comments, success stories, bugs and |
---|
203 | patches. |
---|
204 | |
---|
205 | What the RTEMS project describes here to develop, maintain and use RTEMS does |
---|
206 | not dictate what you need to use in your project. You can and should select the |
---|
207 | work-flow that best suites the demands of your project and what you are |
---|
208 | delivering. |
---|
209 | |
---|
210 | Rational |
---|
211 | -------- |
---|
212 | |
---|
213 | RTEMS is complex and the focus of the RTEMS Ecosystem is to simplify the |
---|
214 | complexity for users by providing a stable documented way to build, configure |
---|
215 | and run RTEMS. RTEMS is more than a kernel running real-time applications on |
---|
216 | target hardware, it is part of a project's and therefore team's workflow and |
---|
217 | every project and team is different. |
---|
218 | |
---|
219 | RTEMS's ecosystem does not mandate a way to work. It is a series of parts, |
---|
220 | components, and items that are used to create a suitable development |
---|
221 | environment to work with. The processes explained in this manual are the same |
---|
222 | things an RTEMS maintainer does to maintain the kernel or an experienced user |
---|
223 | does to build their production system. It is important to keep this in mind |
---|
224 | when working through this manual. We encourage users to explore what can be |
---|
225 | done and to discover ways to make it fit their needs. The ecosystem provided by |
---|
226 | the RTEMS Project will not install in a single click of a mouse because we want |
---|
227 | users to learn the parts they will come to depend on as their project's |
---|
228 | development matures. |
---|
229 | |
---|
230 | The RTEMS Ecosystem provides a standard interface that is the same on all |
---|
231 | supported host systems. Standardizing how a user interacts with RTEMS is |
---|
232 | important and making that experience portable is also important. As a result |
---|
233 | the ecosystem is documented at the command line level and we leave GUI and IDE |
---|
234 | integration for users and integrators. |
---|
235 | |
---|
236 | Standardizing the parts and how to use them lets users create processes and |
---|
237 | procedures that are stable over releases. The RTEMS Ecosystem generates data |
---|
238 | that can be used to audit the build process so their configuration can be |
---|
239 | documented. |
---|
240 | |
---|
241 | The ecosystem is based around the source code used in the various parts, |
---|
242 | components and items of the RTEMS development environment. A user can create |
---|
243 | an archive of the complete build process including all the source code for long |
---|
244 | term storage. This is important for projects with a long life cycle. |
---|
245 | |
---|
246 | Open Source |
---|
247 | ----------- |
---|
248 | |
---|
249 | RTEMS is an open source operating system and an open source project and this |
---|
250 | extends to the ecosystem. We encourage users to integrate the processes to |
---|
251 | build tools, the kernel and any 3rd party libraries into their project's |
---|
252 | configuration management processes. |
---|
253 | |
---|
254 | All the parts that make up the ecosystem are open source. The ecosystem uses a |
---|
255 | package's source code to create an executable on a host so when an example |
---|
256 | RTEMS executable is created and run for the first time the user will have built |
---|
257 | every tool as well as the executable from source. The RTEMS Project believes |
---|
258 | the freedom this gives a user is as important as the freedom of having access |
---|
259 | to the source code for a package. |
---|
260 | |
---|
261 | Deployment |
---|
262 | ---------- |
---|
263 | |
---|
264 | The RTEMS Project provides the ecosystem as source code that users can download |
---|
265 | to create personalised development environments. The RTEMS Project does not |
---|
266 | provide packaging and deployment for a specific host environment, target |
---|
267 | architecture or BSP. The RTEMS Project encourages users and organizations to |
---|
268 | fill this role for the community. The :ref:`RTEMS Source Builder <RSB>` |
---|
269 | provides some aid to :ref:`build and deploy tool binaries <RSBDeployment>`. |
---|
270 | |
---|
271 | Support |
---|
272 | ======= |
---|
273 | .. index:: Support |
---|
274 | |
---|
275 | RTEMS offers a variety of support options. |
---|
276 | |
---|
277 | This section covers all options available to both users and developers. If you |
---|
278 | believe this is a bug report please submit it to the bug tracker otherwise the |
---|
279 | developers mailing list is the default location to send the report. |
---|
280 | |
---|
281 | RTEMS Project Support |
---|
282 | --------------------- |
---|
283 | .. index:: RTEMS Project Support |
---|
284 | |
---|
285 | The following support channels are provided by the RTEMS Project and provide |
---|
286 | direct access to the RTEMS community. |
---|
287 | |
---|
288 | Bug Tracker |
---|
289 | ~~~~~~~~~~~ |
---|
290 | .. index:: Bugs |
---|
291 | .. index:: Reporting bugs |
---|
292 | |
---|
293 | The bug tracker can be found at the :r:url:`bugs`. |
---|
294 | |
---|
295 | See the `Submission Guidelines <http://devel.rtems.org/wiki/NewTicket/>`_ for |
---|
296 | details on submitting a ticket. |
---|
297 | |
---|
298 | Be sure to do a cursory search for any tickets that may be relevant to your |
---|
299 | problem. |
---|
300 | |
---|
301 | If you are unsure about your issue status submit a ticket and we will help you |
---|
302 | sort it out. |
---|
303 | |
---|
304 | Documentation |
---|
305 | ~~~~~~~~~~~~~ |
---|
306 | |
---|
307 | The latest user documentation can always be found at the :r:url:`docs`. |
---|
308 | |
---|
309 | .. _support-mailing-lists: |
---|
310 | |
---|
311 | Mailing Lists |
---|
312 | ~~~~~~~~~~~~~ |
---|
313 | .. index:: Community |
---|
314 | .. index:: Mailing lists |
---|
315 | |
---|
316 | We have several mailing lists for RTEMS users and developers. |
---|
317 | |
---|
318 | * :r:list:`announce` |
---|
319 | * Announcements for major and other project-related issues. |
---|
320 | |
---|
321 | * :r:list:`bugs` |
---|
322 | * Bugs email from :r:url:`bugs`. |
---|
323 | |
---|
324 | * :r:list:`devel` |
---|
325 | * Developers list, this is for developers of RTEMS itself. |
---|
326 | |
---|
327 | |
---|
328 | * :r:list:`build` |
---|
329 | * Results from the testing and building of RTEMS. |
---|
330 | |
---|
331 | * :r:list:`users` |
---|
332 | * Users of RTEMS. |
---|
333 | |
---|
334 | * :r:list:`vc` |
---|
335 | * Commits to the RTEMS master repository. |
---|
336 | |
---|
337 | |
---|
338 | IRC |
---|
339 | ~~~ |
---|
340 | .. index:: Community |
---|
341 | .. index:: IRC |
---|
342 | |
---|
343 | RTEMS IRC is available on the Freenode network. See the `Freenode |
---|
344 | <http://www.freenode.net/>`_ web site for details on connecting, selecting a |
---|
345 | nickname, and general usage tips. If you are new to IRC it is recommended |
---|
346 | reading. |
---|
347 | |
---|
348 | These are the current IRC channels. |
---|
349 | |
---|
350 | **#rtems** |
---|
351 | |
---|
352 | This is a general channel for all things RTEMS. You can just hang out with |
---|
353 | other RTEMS users and developers to talk about RTEMS, using RTEMS or to make |
---|
354 | contact with other RTEMS users. |
---|
355 | |
---|
356 | The ``#rtems`` channel is logged. You can find the logs at |
---|
357 | http://www.rtems.org/irclogs/. You can search the logs using Google by adding: |
---|
358 | |
---|
359 | **site:rtems.org inurl:irclogs** |
---|
360 | |
---|
361 | to your search terms. |
---|
362 | |
---|
363 | Developers |
---|
364 | ~~~~~~~~~~ |
---|
365 | .. index:: Community |
---|
366 | .. index:: Developers |
---|
367 | |
---|
368 | Developers can find help and support on the mailing lists, see |
---|
369 | :ref:`support-mailing-lists`. |
---|
370 | |
---|
371 | Technical documents including design, :r:url:`gsoc`, :r:url:`socis` can be |
---|
372 | found on the :r:url:`devel`. |
---|
373 | |
---|
374 | Commercial Support Services |
---|
375 | --------------------------- |
---|
376 | |
---|
377 | The wider RTEMS community has developers and organizations who can provide |
---|
378 | commercial support services. These services range from training, implementing |
---|
379 | new features in RTEMS, deployment of RTEMS< helping establish a new project |
---|
380 | environment for a team, to application and system design. |
---|
381 | |
---|
382 | The RTEMS Project does not endorse or promote any provider of these services |
---|
383 | and we recommend you use a search engine to locate a suitable provider. If you |
---|
384 | are unsure please contact a provider and see what is available. |
---|
385 | |
---|
386 | If you develop a new feature or you have someone do this for you we recommend |
---|
387 | you have the work submitted to the project and merged. Once accepted into the |
---|
388 | project the work will be maintained as part of the development process within |
---|
389 | the project and this is a benefit for. |
---|
390 | |
---|
391 | Real-time Application Systems |
---|
392 | ============================= |
---|
393 | |
---|
394 | Real-time application systems are a special class of computer applications. |
---|
395 | They have a complex set of characteristics that distinguish them from other |
---|
396 | software problems. Generally, they must adhere to more rigorous requirements. |
---|
397 | The correctness of the system depends not only on the results of computations, |
---|
398 | but also on the time at which the results are produced. The most important and |
---|
399 | complex characteristic of real-time application systems is that they must |
---|
400 | receive and respond to a set of external stimuli within rigid and critical time |
---|
401 | constraints referred to as deadlines. Systems can be buried by an avalanche of |
---|
402 | interdependent, asynchronous or cyclical event streams. |
---|
403 | |
---|
404 | Deadlines can be further characterized as either hard or soft based upon the |
---|
405 | value of the results when produced after the deadline has passed. A deadline |
---|
406 | is hard if the results have no value after the deadline has passed, or a |
---|
407 | catastrophic event results from their intended use if not completed on time. In |
---|
408 | contrast, results produced after a soft deadline may still have some value. |
---|
409 | |
---|
410 | Another distinguishing requirement of real-time application systems is the |
---|
411 | ability to coordinate or manage a large number of concurrent activities. Since |
---|
412 | software is a synchronous entity, this presents special problems. One |
---|
413 | instruction follows another in a repeating synchronous cycle. Even though |
---|
414 | mechanisms have been developed to allow for the processing of external |
---|
415 | asynchronous events, the software design efforts required to process and manage |
---|
416 | these events and tasks are growing more complicated. |
---|
417 | |
---|
418 | The design process is complicated further by spreading this activity over a set |
---|
419 | of processors instead of a single processor. The challenges associated with |
---|
420 | designing and building real-time application systems become very complex when |
---|
421 | multiple processors are involved. New requirements such as interprocessor |
---|
422 | communication channels and global resources that must be shared between |
---|
423 | competing processors are introduced. The ramifications of multiple processors |
---|
424 | complicate each and every characteristic of a real-time system. |
---|
425 | |
---|
426 | Real-time Executive |
---|
427 | =================== |
---|
428 | |
---|
429 | Fortunately, real-time operating systems, or real-time executives, serve as a |
---|
430 | cornerstone on which to build the application system. A real-time multitasking |
---|
431 | executive allows an application to be cast into a set of logical, autonomous |
---|
432 | processes or tasks which become quite manageable. Each task is internally |
---|
433 | synchronous, but different tasks execute independently, resulting in an |
---|
434 | asynchronous processing stream. Tasks can be dynamically paused for many |
---|
435 | reasons resulting in a different task being allowed to execute for a period of |
---|
436 | time. The executive also provides an interface to other system components such |
---|
437 | as interrupt handlers and device drivers. System components may request the |
---|
438 | executive to allocate and coordinate resources, and to wait for and trigger |
---|
439 | synchronizing conditions. The executive system calls effectively extend the |
---|
440 | CPU instruction set to support efficient multitasking. By causing tasks to |
---|
441 | travel through well-defined state transitions, system calls permit an |
---|
442 | application to demand-switch between tasks in response to real-time events. |
---|
443 | |
---|
444 | By properly grouping stimuli responses into separate tasks a system can now |
---|
445 | asynchronously switch between independent streams of execution. This allows the |
---|
446 | system to directly respond to external stimuli as they occur, as well as meet |
---|
447 | critical performance specifications that are typically measured by guaranteed |
---|
448 | response time and transaction throughput. The multiprocessor extensions of |
---|
449 | RTEMS provide the features necessary to manage the extra requirements |
---|
450 | introduced by a system distributed across several processors. It removes the |
---|
451 | physical barriers of processor boundaries from the world of the system |
---|
452 | designer, enabling more critical aspects of the system to receive the required |
---|
453 | attention. Such a system, based on an efficient real-time, multiprocessor |
---|
454 | executive, is a more realistic model of the outside world or environment for |
---|
455 | which it is designed. As a result, the system will always be more logical, |
---|
456 | efficient, and reliable. |
---|
457 | |
---|
458 | By using the directives provided by RTEMS, the real-time applications developer |
---|
459 | is freed from the problem of controlling and synchronizing multiple tasks and |
---|
460 | processors. In addition, one need not develop, test, debug, and document |
---|
461 | routines to manage memory, pass messages, or provide mutual exclusion. The |
---|
462 | developer is then able to concentrate solely on the application. By using |
---|
463 | standard software components, the time and cost required to develop |
---|
464 | sophisticated real-time applications are significantly reduced. |
---|
465 | |
---|
466 | .. [#] The goal is to use the |
---|
467 | `BSD 2-Clause license |
---|
468 | <https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause>`_ for new code |
---|
469 | or code those copyright holder agreed to a license change, see `#3053 |
---|
470 | <https://devel.rtems.org/ticket/3053>`_ for the details. |
---|
471 | |
---|
472 | .. [#] See `#2832 <https://devel.rtems.org/ticket/2832>`_. |
---|
473 | |
---|
474 | .. [#] Thread-local storage requires some support by the tool chain and the |
---|
475 | RTEMS architecture support, e.g. context-switch code. It is supported |
---|
476 | at least on ARM, PowerPC, RISC-V, SPARC and m68k. Check the |
---|
477 | `RTEMS CPU Architecture Supplement <https://docs.rtems.org/branches/master/cpu-supplement.pdf>`_ |
---|
478 | if it is supported. |
---|