source: rtems-docs/user/overview/index.rst @ c098290

5
Last change on this file since c098290 was c098290, checked in by Sebastian Huber <sebastian.huber@…>, on 01/11/19 at 11:54:20

user: Move "Ecosystem" into "Introduction"

  • Property mode set to 100644
File size: 23.3 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
4
5Introduction
6************
7
8Overview
9========
10
11You 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
21Features
22========
23
24The Real-Time Executive for Multiprocessor Systems (:ref:term:`RTEMS`) is a
25multi-threaded, single address-space, real-time operating system with no
26kernel-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
29RTEMS 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
32software used and distributed by RTEMS which may be linked to the application
33is licensed under permissive open source licenses.  Everything necessary to
34build RTEMS applications is available as open source software.  This makes you
35completely vendor independent.
36
37RTEMS 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
189Ecosystem
190=========
191.. index:: Ecosystem
192
193The RTEMS Ecosystem is the collection of tools, packages, code, documentation
194and online content provided by the RTEMS Project. The ecosystem provides a way
195to develop, maintain, and use RTEMS. It's parts interact with the user, the
196host environment, and each other to make RTEMS accessible, useable and
197predicable.
198
199The ecosystem is for users, developers and maintainers and it is an ongoing
200effort that needs your help and support. The RTEMS project is always improving
201the way it delivers the kernel to you and your feedback is important so please
202join the mailing lists and contribute back comments, success stories, bugs and
203patches.
204
205What the RTEMS project describes here to develop, maintain and use RTEMS does
206not dictate what you need to use in your project. You can and should select the
207work-flow that best suites the demands of your project and what you are
208delivering.
209
210Rational
211--------
212
213RTEMS is complex and the focus of the RTEMS Ecosystem is to simplify the
214complexity for users by providing a stable documented way to build, configure
215and run RTEMS. RTEMS is more than a kernel running real-time applications on
216target hardware, it is part of a project's and therefore team's workflow and
217every project and team is different.
218
219RTEMS's ecosystem does not mandate a way to work. It is a series of parts,
220components, and items that are used to create a suitable development
221environment to work with. The processes explained in this manual are the same
222things an RTEMS maintainer does to maintain the kernel or an experienced user
223does to build their production system. It is important to keep this in mind
224when working through this manual. We encourage users to explore what can be
225done and to discover ways to make it fit their needs. The ecosystem provided by
226the RTEMS Project will not install in a single click of a mouse because we want
227users to learn the parts they will come to depend on as their project's
228development matures.
229
230The RTEMS Ecosystem provides a standard interface that is the same on all
231supported host systems. Standardizing how a user interacts with RTEMS is
232important and making that experience portable is also important. As a result
233the ecosystem is documented at the command line level and we leave GUI and IDE
234integration for users and integrators.
235
236Standardizing the parts and how to use them lets users create processes and
237procedures that are stable over releases. The RTEMS Ecosystem generates data
238that can be used to audit the build process so their configuration can be
239documented.
240
241The ecosystem is based around the source code used in the various parts,
242components and items of the RTEMS development environment. A user can create
243an archive of the complete build process including all the source code for long
244term storage. This is important for projects with a long life cycle.
245
246Open Source
247-----------
248
249RTEMS is an open source operating system and an open source project and this
250extends to the ecosystem. We encourage users to integrate the processes to
251build tools, the kernel and any 3rd party libraries into their project's
252configuration management processes.
253
254All the parts that make up the ecosystem are open source. The ecosystem uses a
255package's source code to create an executable on a host so when an example
256RTEMS executable is created and run for the first time the user will have built
257every tool as well as the executable from source. The RTEMS Project believes
258the freedom this gives a user is as important as the freedom of having access
259to the source code for a package.
260
261Deployment
262----------
263
264The RTEMS Project provides the ecosystem as source code that users can download
265to create personalised development environments. The RTEMS Project does not
266provide packaging and deployment for a specific host environment, target
267architecture or BSP. The RTEMS Project encourages users and organizations to
268fill this role for the community.
269
270Building and Deploying Tool Binaries
271~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272
273If you wish to create and distribute your build or you want to archive a build
274you can create a tar file. We term this deploying a build. This is a more
275advanced method for binary packaging and installing of tools.
276
277By default the RTEMS Source Builder installs the built packages directly and
278optionally it can also create a *build set tar file* or a *package tar file*
279per package built. The normal and default behaviour is to let the RTEMS Source
280Builder install the tools. The source will be downloaded, built, installed and
281cleaned up.
282
283The tar files are created with the full build prefix present and if you follow
284the examples given in this documentation the path is absolute. This can cause
285problems if you are installing on a host you do not have super user or
286administrator rights on because the prefix path may references part you do not
287have write access too and tar will not extract the files. You can use the
288``--strip-components`` option in tar if your host tar application supports it
289to remove the parts you do not have write access too or you may need to unpack
290the tar file somewhere and copy the file tree from the level you have write
291access from. Embedding the full prefix path in the tar files lets you know what
292the prefix is and is recommended. For example if
293``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
294directory to the root (``/``) and untar the file because the ``/home`` is root
295access only. To install a tar file you have downloaded into your new machine's
296``Downloads`` directory in your home directoty you would enter:
297
298.. code-block:: shell
299
300    $ cd /somewhere
301    $ tar --strip-components=3 -xjf \
302          $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
303
304A build set tar file is created by adding ``--bset-tar-file`` option to the
305``sb-set-builder`` command::
306
307    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
308             --prefix=$HOME/development/rtems/4.11 \
309             --bset-tar-file \     <1>
310             4.11/rtems-sparc
311    Source Builder - Set Builder, v0.2.0
312    Build Set: 4.11/rtems-sparc
313    config: expat-2.1.0-1.cfg
314    package: expat-2.1.0-x86_64-freebsd9.1-1
315    building: expat-2.1.0-x86_64-freebsd9.1-1
316    config: tools/rtems-binutils-2.22-1.cfg
317    package: sparc-rtems4.11-binutils-2.22-1
318    building: sparc-rtems4.11-binutils-2.22-1
319    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
320    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
321    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
322    config: tools/rtems-gdb-7.5.1-1.cfg
323    package: sparc-rtems4.11-gdb-7.5.1-1
324    building: sparc-rtems4.11-gdb-7.5.1-1
325    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
326    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
327    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
328    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
329    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2      <3>
330    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
331    cleaning: sparc-rtems4.11-binutils-2.22-1
332    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
333    cleaning: sparc-rtems4.11-gdb-7.5.1-1
334    Build Set: Time 0:15:25.92873
335
336.. topic:: Items
337
338  1. The option to create a build set tar file.
339
340  2. The installation still happens unless you specify ``--no-install``.
341
342  3. Creating the build set tar file.
343
344You can also suppress installing the files using the ``--no-install``
345option. This is useful if your prefix is not accessiable, for example when
346building Canadian cross compiled tool sets::
347
348    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
349                --prefix=$HOME/development/rtems/4.11 \
350                --bset-tar-file \
351                --no-install \      <1>
352                4.11/rtems-sparc
353    Source Builder - Set Builder, v0.2.0
354    Build Set: 4.11/rtems-sparc
355    config: expat-2.1.0-1.cfg
356    package: expat-2.1.0-x86_64-freebsd9.1-1
357    building: expat-2.1.0-x86_64-freebsd9.1-1
358    config: tools/rtems-binutils-2.22-1.cfg
359    package: sparc-rtems4.11-binutils-2.22-1
360    building: sparc-rtems4.11-binutils-2.22-1
361    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
362    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
363    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
364    config: tools/rtems-gdb-7.5.1-1.cfg
365    package: sparc-rtems4.11-gdb-7.5.1-1
366    building: sparc-rtems4.11-gdb-7.5.1-1
367    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2    <2>
368    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
369    cleaning: sparc-rtems4.11-binutils-2.22-1
370    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
371    cleaning: sparc-rtems4.11-gdb-7.5.1-1
372    Build Set: Time 0:14:11.721274
373    $ ls tar
374    rtems-4.11-sparc-rtems4.11-1.tar.bz2
375
376.. topic:: Items
377
378  1. The option to supressing installing the packages.
379
380  2. Create the build set tar.
381
382A package tar file can be created by adding the ``--pkg-tar-files`` to the
383``sb-set-builder`` command. This creates a tar file per package built in the
384build set::
385
386    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
387            --prefix=$HOME/development/rtems/4.11 \
388            --bset-tar-file \
389            --pkg-tar-files \        <1>
390            --no-install 4.11/rtems-sparc
391    Source Builder - Set Builder, v0.2.0
392    Build Set: 4.11/rtems-sparc
393    config: expat-2.1.0-1.cfg
394    package: expat-2.1.0-x86_64-freebsd9.1-1
395    building: expat-2.1.0-x86_64-freebsd9.1-1
396    config: tools/rtems-binutils-2.22-1.cfg
397    package: sparc-rtems4.11-binutils-2.22-1
398    building: sparc-rtems4.11-binutils-2.22-1
399    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
400    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
401    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
402    config: tools/rtems-gdb-7.5.1-1.cfg
403    package: sparc-rtems4.11-gdb-7.5.1-1
404    building: sparc-rtems4.11-gdb-7.5.1-1
405    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
406    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
407    cleaning: sparc-rtems4.11-binutils-2.22-1
408    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
409    cleaning: sparc-rtems4.11-gdb-7.5.1-1
410    Build Set: Time 0:14:37.658460
411    $ ls tar
412    expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
413    sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
414    sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
415
416.. topic:: Items
417
418  1. The option to create packages tar files.
419
420  2. The GDB package tar file.
421
422  3. The build set tar file. All the others in a single tar file.
423
424Support
425=======
426.. index:: Support
427
428RTEMS offers a variety of support options.
429
430This section covers all options available to both users and developers.  If you
431believe this is a bug report please submit it to the bug tracker otherwise the
432developers mailing list is the default location to send the report.
433
434RTEMS Project Support
435---------------------
436.. index:: RTEMS Project Support
437
438The following support channels are provided by the RTEMS Project and provide
439direct access to the RTEMS community.
440
441Bug Tracker
442~~~~~~~~~~~
443.. index:: Bugs
444.. index:: Reporting bugs
445
446The bug tracker can be found at the :r:url:`bugs`.
447
448See the `Submission Guidelines <http://devel.rtems.org/wiki/NewTicket/>`_ for
449details on submitting a ticket.
450
451Be sure to do a cursory search for any tickets that may be relevant to your
452problem.
453
454If you are unsure about your issue status submit a ticket and we will help you
455sort it out.
456
457Documentation
458~~~~~~~~~~~~~
459
460The latest user documentation can always be found at the :r:url:`docs`.
461
462.. _support-mailing-lists:
463
464Mailing Lists
465~~~~~~~~~~~~~
466.. index:: Community
467.. index:: Mailing lists
468
469We have several mailing lists for RTEMS users and developers.
470
471        * :r:list:`announce`
472                * Announcements for major and other project-related issues.
473
474        * :r:list:`bugs`
475                * Bugs email from :r:url:`bugs`.
476
477        * :r:list:`devel`
478                * Developers list, this is for developers of RTEMS itself.
479
480
481        * :r:list:`build`
482                * Results from the testing and building of RTEMS.
483
484        * :r:list:`users`
485                * Users of RTEMS.
486
487        * :r:list:`vc`
488                * Commits to the RTEMS master repository.
489
490
491IRC
492~~~
493.. index:: Community
494.. index:: IRC
495
496RTEMS IRC is available on the Freenode network. See the `Freenode
497<http://www.freenode.net/>`_ web site for details on connecting, selecting a
498nickname, and general usage tips. If you are new to IRC it is recommended
499reading.
500
501These are the current IRC channels.
502
503  **#rtems**
504
505This is a general channel for all things RTEMS. You can just hang out with
506other RTEMS users and developers to talk about RTEMS, using RTEMS or to make
507contact with other RTEMS users.
508
509The ``#rtems`` channel is logged. You can find the logs at
510http://www.rtems.org/irclogs/. You can search the logs using Google by adding:
511
512  **site:rtems.org inurl:irclogs**
513
514to your search terms.
515
516Developers
517~~~~~~~~~~
518.. index:: Community
519.. index:: Developers
520
521Developers can find help and support on the mailing lists, see
522:ref:`support-mailing-lists`.
523
524Technical documents including design, :r:url:`gsoc`, :r:url:`socis` can be
525found on the :r:url:`devel`.
526
527Commercial Support Services
528---------------------------
529
530The wider RTEMS community has developers and organizations who can provide
531commercial support services. These services range from training, implementing
532new features in RTEMS, deployment of RTEMS< helping establish a new project
533environment for a team, to application and system design.
534
535The RTEMS Project does not endorse or promote any provider of these services
536and we recommend you use a search engine to locate a suitable provider. If you
537are unsure please contact a provider and see what is available.
538
539If you develop a new feature or you have someone do this for you we recommend
540you have the work submitted to the project and merged. Once accepted into the
541project the work will be maintained as part of the development process within
542the project and this is a benefit for.
543
544Real-time Application Systems
545=============================
546
547Real-time application systems are a special class of computer applications.
548They have a complex set of characteristics that distinguish them from other
549software problems.  Generally, they must adhere to more rigorous requirements.
550The correctness of the system depends not only on the results of computations,
551but also on the time at which the results are produced.  The most important and
552complex characteristic of real-time application systems is that they must
553receive and respond to a set of external stimuli within rigid and critical time
554constraints referred to as deadlines.  Systems can be buried by an avalanche of
555interdependent, asynchronous or cyclical event streams.
556
557Deadlines can be further characterized as either hard or soft based upon the
558value of the results when produced after the deadline has passed.  A deadline
559is hard if the results have no value after the deadline has passed, or a
560catastrophic event results from their intended use if not completed on time.  In
561contrast, results produced after a soft deadline may still have some value.
562
563Another distinguishing requirement of real-time application systems is the
564ability to coordinate or manage a large number of concurrent activities. Since
565software is a synchronous entity, this presents special problems.  One
566instruction follows another in a repeating synchronous cycle.  Even though
567mechanisms have been developed to allow for the processing of external
568asynchronous events, the software design efforts required to process and manage
569these events and tasks are growing more complicated.
570
571The design process is complicated further by spreading this activity over a set
572of processors instead of a single processor. The challenges associated with
573designing and building real-time application systems become very complex when
574multiple processors are involved.  New requirements such as interprocessor
575communication channels and global resources that must be shared between
576competing processors are introduced.  The ramifications of multiple processors
577complicate each and every characteristic of a real-time system.
578
579Real-time Executive
580===================
581
582Fortunately, real-time operating systems, or real-time executives, serve as a
583cornerstone on which to build the application system.  A real-time multitasking
584executive allows an application to be cast into a set of logical, autonomous
585processes or tasks which become quite manageable.  Each task is internally
586synchronous, but different tasks execute independently, resulting in an
587asynchronous processing stream.  Tasks can be dynamically paused for many
588reasons resulting in a different task being allowed to execute for a period of
589time.  The executive also provides an interface to other system components such
590as interrupt handlers and device drivers.  System components may request the
591executive to allocate and coordinate resources, and to wait for and trigger
592synchronizing conditions.  The executive system calls effectively extend the
593CPU instruction set to support efficient multitasking.  By causing tasks to
594travel through well-defined state transitions, system calls permit an
595application to demand-switch between tasks in response to real-time events.
596
597By properly grouping stimuli responses into separate tasks a system can now
598asynchronously switch between independent streams of execution. This allows the
599system to directly respond to external stimuli as they occur, as well as meet
600critical performance specifications that are typically measured by guaranteed
601response time and transaction throughput.  The multiprocessor extensions of
602RTEMS provide the features necessary to manage the extra requirements
603introduced by a system distributed across several processors.  It removes the
604physical barriers of processor boundaries from the world of the system
605designer, enabling more critical aspects of the system to receive the required
606attention. Such a system, based on an efficient real-time, multiprocessor
607executive, is a more realistic model of the outside world or environment for
608which it is designed.  As a result, the system will always be more logical,
609efficient, and reliable.
610
611By using the directives provided by RTEMS, the real-time applications developer
612is freed from the problem of controlling and synchronizing multiple tasks and
613processors.  In addition, one need not develop, test, debug, and document
614routines to manage memory, pass messages, or provide mutual exclusion.  The
615developer is then able to concentrate solely on the application.  By using
616standard software components, the time and cost required to develop
617sophisticated real-time applications are significantly reduced.
618
619.. [#] The goal is to use the
620       `BSD 2-Clause license
621       <https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause>`_ for new code
622       or code those copyright holder agreed to a license change, see `#3053
623       <https://devel.rtems.org/ticket/3053>`_ for the details.
624
625.. [#] See `#2832 <https://devel.rtems.org/ticket/2832>`_.
626
627.. [#] Thread-local storage requires some support by the tool chain and the
628       RTEMS architecture support, e.g. context-switch code.  It is supported
629       at least on ARM, PowerPC, RISC-V, SPARC and m68k.  Check the
630       `RTEMS CPU Architecture Supplement <https://docs.rtems.org/branches/master/cpu-supplement.pdf>`_
631       if it is supported.
Note: See TracBrowser for help on using the repository browser.