[PATCH rtems-docs v2 1/2] Added FAQ page
Ayushman Mishra
ayushvidushi01 at gmail.com
Fri Apr 2 18:18:36 UTC 2021
---
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
More information about the devel
mailing list