--- user/bld/index.rst | 2 + user/overview/index.rst | 2 + user/start/faq.rst | 295 +++++++++++++++++++++++++++++++ user/start/index.rst | 1 + user/support/contrib.rst | 96 +--------- user/support/support-project.rst | 2 + 6 files changed, 303 insertions(+), 95 deletions(-) create mode 100644 user/start/faq.rst
diff --git a/user/bld/index.rst b/user/bld/index.rst index ebedf5a..0cccde2 100644 --- a/user/bld/index.rst +++ b/user/bld/index.rst @@ -284,6 +284,8 @@ example configuration file, building of the tests is enabled for the [riscv/griscv] +.. _Migration_from_AutoconfAutomake: + Migration from Autoconf/Automake ================================ diff --git a/user/overview/index.rst b/user/overview/index.rst index 550724a..0703ede 100644 --- a/user/overview/index.rst +++ b/user/overview/index.rst @@ -20,6 +20,8 @@ You are someone looking for a real-time operating system. This document - helps you to build an example application on top of RTEMS. +.. _Features: + Features ======== diff --git a/user/start/faq.rst b/user/start/faq.rst new file mode 100644 index 0000000..910ef8b --- /dev/null +++ b/user/start/faq.rst @@ -0,0 +1,295 @@ +Frequently Asked Questions +========================== + +What is RTEMS ? +----------------------------------- + +RTEMS is an open source real-time executive which provides a high performance +environment for embedded real-time applications including many features. + +The RTEMS Project is the umbrella term used to describe the collection of +individuals, companies, universities, and research institutions that collectively +maintain and enhance the RTEMS software base. + +RTEMS is designed to support applications with the most stringent real-time +requirements while being compatible with open standards such as POSIX. +RTEMS includes optional functional features such as TCP/IP and various file +systems while still offering minimum executable sizes under 20 KB in useful +configurations. + +:ref:`More Features<Features>` + +Where can I get RTEMS ? +----------------------------------------------------------------- + +:ref:`Downloading RTEMS<QuickStartSources_Released>` + +What does RTEMS stand for ? +------------------------------------------------- + +RTEMS is an an acronym for the Real-Time Executive for Multiprocessor Systems. + +Initially RTEMS stood for the Real-Time Executive for Missile Systems but as it +became clear that the application domains that could use RTEMS extended far +beyond missiles, the "M" changed to mean Military. When maintenance of RTEMS +transferred to OAR, the "M" was changed again to Multiprocessor. + +At one point, there were both Ada and C implementations of RTEMS. +Version 3.2.1 was the last RTEMS version to have implementations in both +languages. Supporting the Classic API Ada implementation was painful and fraught +with compiler specific pitfalls. With version 3.5.x, the POSIX API was added as +the means to support the GNU Ada Translator (GNAT). This effectively eliminated +the need for an implementation in Ada as the C implementation could effectively +support both languages. + +Are there restrictions on the RTEMS License ? +-------------------------------------------- + +RTEMS RTEMS is licensed under a combination of permissive licenses and a +modified version of the GNU General Public License (GPL). +For source code "Two Clause BSD” (BSD-2-Clause) and +for documentation CC-BY-SA-4.0 license is preferred. +The modification places no restrictions on the applications which use RTEMS but +protects the interests of those who work on RTEMS. + +`License in RTEMS +<https://docs.rtems.org/branches/master/eng/ +license-requirements.html>`__ + +What standards are supported by RTEMS? +--------------------------------------------------------- + +The original "Classic" RTEMS API is based on the Real-Time Executive Interface +Definition (RTEID) and the Open Real-Time Kernel Interface Definition (ORKID). +RTEMS also includes support for POSIX threads and real-time extensions. + +With the addition of file system infrastructure, RTEMS supports approximately +80% of the POSIX 1003.1b-1996 standard. This standard defines the programming +interfaces of standard UNIX. This means that much source code that works on +UNIX, also works on RTEMS.RTEMS includes a port of the FreeBSD TCP/IP stack and +thus supports BSD sockets. It also includes support for numerous networking +clients (DHCP, TFTP, NFS, etc.) and servers (FTPD, HTTPD, etc.). + +What processors is RTEMS available for ? +---------------------------------------------------------- + +:ref:`Architectures in RTEMS<TargetArchitectures>` + +Are there similar commercial products ? +-------------------------------------------- + +`Some Real time operating system similar to RTEMS +<https://en.wikipedia.org/wiki/Comparison_of_real-time_operating_systems>`__ + +How can I obtain RTEMS support ? +----------------------------------------------------- + +:ref:`Support in RTEMS<RTEMS_Project_Support>` + +What RTEMS Training Opportunities are available ? +-------------------------------------------------- + +`RTEMS Training Opportunities <https://www.rtems.org/TrainingOpportunities>`__ + +How can I contribute? +------------------------------------------- + +:ref:`Contributions in RTEMS<Contributing>` + +How are floating point numbers handled ? +--------------------------------------------- + +`Floating point support in RTEMS +<https://docs.rtems.org/branches/master/c-user/task/ +background.html#floating-point-considerations>`__ + +How do I make a patch ? +-------------------------- + +`Creating and sending patch in RTEMS +<https://docs.rtems.org/branches/master/eng/vc-users.html#creating-a-patch>`__ + +Why is my executable so big? +------------------------------------------------------- + +There are two primary causes for this. The most common is that you are doing an +ls -l and looking at the actual file size – not the size of the code in the +target image. This file could be in an object format such as ELF or COFF and +contain debug information. If this is the case, it could be an order of magnitude +larger than the required code space. Use the strip command in your cross +toolset to remove debugging information. + +Another alternative is that the executable file is in an ASCII format such as +Motorola Srecords. In this case, there is no debug information in the file +but each byte in the target image requires two bytes to represent. On top of +that, there is some overhead required to specify the addresses where the image +is to be placed in target memory as well as checksum information. In this +case, it is not uncommon to see executable files that are between two and three +times larger than the actual space required in target memory. + +Remember, the debugging information is required to do symbolic debugging with gdb. +Normally gdb obtains its symbolic information from the same file that it gets +the exe- cutable image from. However, gdb does not require that the executable +image and symbolic information be obtained from the same file. So you might want +to create a hello_with_ symbols.exe, copy that file to hello_without_symbols.exe, +and strip hello_without_ symbols.exe. Then gdb would have to be told to read +symbol information from hello_ with_symbols.exe. The gdb command line option +-symbols or command symbol-file may be used to specify the file read for +symbolic information + +What MinGW Tools for Windows are available ? +------------------------------------------------------------------------- + +Windows users can use MinGW based RTEMS tools. These tools will generate the +same application code for RTEMS as the tools on Linux or Cygwin. MinGW tools +use the native Windows runtime rather than access Windows via the POSIX interfac +Cygwin provides. MinGW tools are faster than the Cygwin equivalent and are not +confused by Cygwin mount points. Compiler errors will show a Windows path rather +than a Cygwin path and so do not confuse native Windows editors. +:ref:`Cygwin in windows<Cygwin>` + +The RTEMS MinGW Tools are not currently packaged in installers. The installers +stopped around RTEMS 4.9 when the MinGW tools started to be built as part of +the binary tool package. This means you need to manually step through the +process. It is not difficult, how-ever it is not an easy installer. + +What is Multilib RTEMS ? +----------------------------------------------------------------- + +The multilib process supports building a set of related libraries for a given +target where the individual libraries in the set use different specific +compiler flags (such as flags for code generation options, pre-processor +defines, etc) for the individual libraries. The reason this is needed can be +seen by examining the M68K GCC compiler. That compiler generates code for a +number of processor variants in the M68K family, for example, it can generate +code for the original 68000, the 68040 or a 528x Coldfire. These processors all +use a closely related instruction set, but processor differences mean code +compiled for one may not run on another. GCC provides a special library called +libgcc.a that holds intrinsic functions needed by the compiler. These +intrinsic functions provide "software instructions" (such as non-basic math +support routines) that the processor may not support. However, which functions +GCC considers to be intrinsic should be able to vary within a processor family. +One processor variant will have hardware floating point and another processor +variant will not, and GCC (and RTEMS) should be able to generate efficient code +for each processor variant. When we wish to have different code for a range of +related yet potentially incompatible processors in a family by providing +multiple related libraries we use the multilib process. + +The multilib process extends beyond libgcc.a to libc.a, libm.a, and libstd++.a. +An RTEMS tool set will provide each of these libraries for each of the processor +variants that GCC supports. You can see the multilib information by invoking gcc +with the option '-print-multi-lib'. The output for the M68K tool chain is - + +.. code-block:: none + + $ m68k-rtems-gcc -print-multi-lib .; m68000;@m68000 m5200;@m5200 + m5206e;@m5206e m528x;@m528x m5307;@m5307 m5407;@m5407 mcpu32;@mcpu32 + m68040;@m68040 m68060;@m68060 msoft-float;@msoft-float + +This output is not easy to read as it is designed for other tools or packages. + +RTEMS core under the cpukit source tree does not reference any BSP specific +details. This allows it to be built as a set of multiple libraries named +librtemscpu.a. A configure command line option will build a multilib RTEMS as +shown in Building a CPU Kit. + +BSP and CPU model specific portions of RTEMS (libcpu and libbsp) are +built into the separate library librtemsbsp.a. + +What is the difference between the workspace and heap ? +---------------------------------------------------------------------- + +The RTEMS Workspace is used to allocate space for objects created by RTEMS +such as tasks, semaphores, message queues, etc.. It is primarily used during +system initialization although task stacks and message buffer areas are also +allocated from here. + +Why should we work with the RTEMS developers ? +--------------------------------------------------------------------------- + +Our engineers understand our target environment better than anyone else, and +we have a tight schedule. Why should we work with the RTEMS developers, when +we can get the code out faster by whacking it out on our own? + +You understand your target environment better than anyone else. +However, the RTEMS developers understand RTEMS better than anyone +else; furthermore, the RTEMS developers tend to have a wide breadth +of experience across a large number of processors, boards, peripherals, +and application domains. It has been our experience that few problems +encountered in embedded systems development are unique to a particular +processor or application. The vast majority of the time an issue that +arises in one project has also shown up in other projects. + +The intimate knowledge of RTEMS internals as well as a wide breadth of +embedded systems knowledge means that there is a good chance that at +least one RTEMS developer has already addressed issues you are likely +to face when doing your port, BSP, or application. The developers can +help guide you towards a workable long term solution, possibly saving +you significant time in your development cycle. + +If getting the sources into the official RTEMS distributions is one of +your goals, then engaging other RTEMS developers early will also likely +shorten your development time. By interacting as early as possible you +are more likely to write code which can be easily accepted into the official +sources when you are finished. If you wait until you think you are done +to begin interacting with the RTEMS team, you might find that you did +some things wrong and you may have to rewrite parts of your RTEMS port, +which is a waste of your valuable time. + +Why should we integrate our port into the official RTEMS sources? +------------------------------------------------------------------ + +Why should we care if our port is integrated into the official RTEMS sources? +We can distribute it ourselves to whoever is interested. + +Yes, the RTEMS licenses allows you to do that. But by doing so, you end up +having to maintain that code yourself; this can be a significant +effort over time as the RTEMS sources change rapidly. + +You also lose the advantage of wider exposure by including your port +in the official RTEMS sources maintained by the RTEMS Project. +The wider exposure in the RTEMS developer and tester community will +help keep your work up to date with the current sources. You may even +find that volunteers will run the ever-growing test suite on your port +and fix problems during the development cycle -- sometimes without your +intervention. + +It has been our experience that integrated ports tend to ultimately +be of better quality and stay up to date from release to release. + +Aspects of my target environment that my application exploits are still under NDA +--------------------------------------------------------------------------------- + +Nevertheless, if the target hardware is built of any commercial parts +that are generally available including, but not limited to, the CPU +or peripherals, then that portion of your work is still of general use. +Similarly, if you have written software that adheres to existing API or +interface standards, then that portion is also of general use. +Our experience is that most embedded applications do utilize a custom +mix of hardware and application, but they are built upon layers of hardware +and software components that are in no way unique to the project. + +If you are porting to an unreleased CPU family or model, then just +announcing it is important because other RTEMS users may be planning +to use it and some of them may already be trying to port RTEMS on +their own. Your customers might be happier to know that your port +will eventually be available. Also, there is no requirement that RTEMS +include all features or ports at any particular time, so you are encouraged +to submit discrete pieces of functionality in stages. + +Assume that your processor has some new functionality or peripherals. +However that functionality is still covered by NDA, but the basic core +architecture is not. It is still to your advantage to go ahead and work +with the developers early to provide a "base port" for the CPU family. +That base port would only use the publicly available specifications +until such time as the NDA is lifted. Once the NDA is lifted you can +work with the developers to provide the code necessary to take +advantage of the new functionality. + +What is the difference between autoconf and waf build system ? +-------------------------------------------------------------- + +Waf is a build automation tool written in Python which is designed to assist +in the automatic compilation and installation of computer software. +:ref:`Converting from Autoconf/Automake to waf build system +<Migration_from_AutoconfAutomake>` diff --git a/user/start/index.rst b/user/start/index.rst index 17c34e1..e178209 100644 --- a/user/start/index.rst +++ b/user/start/index.rst @@ -23,3 +23,4 @@ applications on top of RTEMS. app rsb-packages gsoc + faq diff --git a/user/support/contrib.rst b/user/support/contrib.rst index c42d41b..758f0f6 100644 --- a/user/support/contrib.rst +++ b/user/support/contrib.rst @@ -168,98 +168,4 @@ time, or have proven very hard to integrate. So, what we are asking is that, to the maximum extent possible, you communicate with us as early on and as much as possible. -Common Questions and Answers -============================ - -Here are some questions RTEMS porters may have with our answers to -them. While the focus here is on new ports and BSPs, we believe that -the issues are similar for other RTEMS development efforts including -student efforts to implement new algorithmic optimizations. - - Our engineers understand our target environment better than anyone else, and - we have a tight schedule. Why should we work with the RTEMS developers, when - we can get the code out faster by whacking it out on our own? - -You understand your target environment better than anyone else. -However, the RTEMS developers understand RTEMS better than anyone -else; furthermore, the RTEMS developers tend to have a wide breadth -of experience across a large number of processors, boards, peripherals, -and application domains. It has been our experience that few problems -encountered in embedded systems development are unique to a particular -processor or application. The vast majority of the time an issue that -arises in one project has also shown up in other projects. - -The intimate knowledge of RTEMS internals as well as a wide breadth of -embedded systems knowledge means that there is a good chance that at -least one RTEMS developer has already addressed issues you are likely -to face when doing your port, BSP, or application. The developers can -help guide you towards a workable long term solution, possibly saving -you significant time in your development cycle. - -If getting the sources into the official RTEMS distributions is one of -your goals, then engaging other RTEMS developers early will also likely -shorten your development time. By interacting as early as possible you -are more likely to write code which can be easily accepted into the official -sources when you are finished. If you wait until you think you are done -to begin interacting with the RTEMS team, you might find that you did -some things wrong and you may have to rewrite parts of your RTEMS port, -which is a waste of your valuable time. - - Why should we care if our port is integrated into the official RTEMS - sources? We can distribute it ourselves to whoever is interested. - -Yes, the RTEMS licenses allows you to do that. But by doing so, you end up -having to maintain that code yourself; this can be a significant -effort over time as the RTEMS sources change rapidly. - -You also lose the advantage of wider exposure by including your port -in the official RTEMS sources maintained by the RTEMS Project. -The wider exposure in the RTEMS developer and tester community will -help keep your work up to date with the current sources. You may even -find that volunteers will run the ever-growing test suite on your port -and fix problems during the development cycle -- sometimes without your -intervention. - -It has been our experience that integrated ports tend to ultimately -be of better quality and stay up to date from release to release. - - Why should we communicate up front? We are happy to let the RTEMS developers - integrate our stuff later. - -See above. It will save work for you over both the short and the -long term, and it is the right thing to do. - - Aspects of my target environment that my application exploits are still - under NDA. - -Nevertheless, if the target hardware is built of any commercial parts -that are generally available including, but not limited to, the CPU -or peripherals, then that portion of your work is still of general use. -Similarly, if you have written software that adheres to existing API or -interface standards, then that portion is also of general use. -Our experience is that most embedded applications do utilize a custom -mix of hardware and application, but they are built upon layers of hardware -and software components that are in no way unique to the project. - -If you are porting to an unreleased CPU family or model, then just -announcing it is important because other RTEMS users may be planning -to use it and some of them may already be trying to port RTEMS on -their own. Your customers might be happier to know that your port -will eventually be available. Also, there is no requirement that RTEMS -include all features or ports at any particular time, so you are encouraged -to submit discrete pieces of functionality in stages. - -Assume that your processor has some new functionality or peripherals. -However that functionality is still covered by NDA, but the basic core -architecture is not. It is still to your advantage to go ahead and work -with the developers early to provide a "base port" for the CPU family. -That base port would only use the publicly available specifications -until such time as the NDA is lifted. Once the NDA is lifted you can -work with the developers to provide the code necessary to take -advantage of the new functionality. - -Ultimately, cooperating with the free software community as early as -possible helps you by decreasing your development cycle, decreasing -your long term maintenance costs and may help raise interest in your -processor by having a free compiler implementation available to -anyone who wants to take a look. + diff --git a/user/support/support-project.rst b/user/support/support-project.rst index b782029..73d5851 100644 --- a/user/support/support-project.rst +++ b/user/support/support-project.rst @@ -6,6 +6,8 @@ .. index:: support; RTEMS Project +.. _RTEMS_Project_Support: + RTEMS Project Support ********************* -- 2.25.1 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel