[PATCH 1/2] Added FAQ page

Ayushman Mishra ayushvidushi01 at gmail.com
Tue Mar 23 18:44:41 UTC 2021

 user/bld/index.rst               |   4 +-
 user/overview/index.rst          |   2 +
 user/start/faq.rst               | 255 +++++++++++++++++++++++++++++++
 user/start/index.rst             |   1 +
 user/support/support-project.rst |   2 +
 5 files changed, 263 insertions(+), 1 deletion(-)
 create mode 100644 user/start/faq.rst

diff --git a/user/bld/index.rst b/user/bld/index.rst
index ebedf5a..a8a8a4f 100644
--- a/user/bld/index.rst
+++ b/user/bld/index.rst
@@ -82,7 +82,7 @@ specifies paths to build specification items.  It is an advanced option and
 there is normally no need to use it.  It may be used to customize the build at
 the level of the build specification.  For more information see the
 `Build System` chapter of the
-`RTEMS Software Engineering <https://docs.rtems.org/branches/master/eng/build-system.rst>`_
+`RTEMS Software Engineering <https://docs.rtems.org/branches/master/eng/build-system.html>`_
@@ -283,6 +283,8 @@ example configuration file, building of the tests is enabled for the
+.. _Autoconf_migration:
 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:
diff --git a/user/start/faq.rst b/user/start/faq.rst
new file mode 100644
index 0000000..da11ca4
--- /dev/null
+++ b/user/start/faq.rst
@@ -0,0 +1,255 @@
+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 
+: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 is licensed under a modified version of the GNU General Public License (GPL).
+The modification places no restrictions on the applications which use RTEMS but
+protects the interests of those who work on RTEMS.
+`License in RTEMS
+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 
+How can I obtain ​RTEMS support ?
+:ref:`Support in RTEMS<Support_project>`
+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
+How do I make a patch ?
+The recommended way to create a patch is to branch the git repository master 
+and use one commit for each logical change. Then you can use git-format-patch 
+to turn your commits into patches and easily submit them.
+.. code-block:: none
+    git format-patch master
+Creates a separate patch for each commit that has been made between the master 
+branch and the current branch and writes them in the current directory. Use 
+the -o flag to redirect the files to a different directory.
+If you are re-submitting a patch that has previously been reviewed, you should 
+specify a version number for your patch, for example, use
+.. code-block:: none
+    git format-patch -v2 ... 
+to indicate the second version of a patch, v3 for a third, and so forth.
+Patches created using git-format-patch are formatted so they can be emailed 
+and rely on having git configured with your name and email address, for example
+.. code-block:: none
+    git config --global user.name "Your Name"
+    git config --global user.email name at domain.com
+Please use a real name, we do not allow pseudonyms or anonymous contributions.
+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 interface 
+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.
+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<Autoconf_migration>`
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.
+    faq
diff --git a/user/support/support-project.rst b/user/support/support-project.rst
index b782029..9973f5a 100644
--- a/user/support/support-project.rst
+++ b/user/support/support-project.rst
@@ -6,6 +6,8 @@
 .. index:: support; RTEMS Project
+.. _Support_project:
 RTEMS Project Support

More information about the devel mailing list