[PATCH 1/2] Added FAQ page

Tue Mar 23 19:34:53 UTC 2021

Did you build the docs and verify they look good?

On Tue, Mar 23, 2021 at 12:44 PM Ayushman Mishra
<ayushvidushi01 at gmail.com> wrote:
>
> ---
>  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>`_
>  guide.
>
>  Help
> @@ -283,6 +283,8 @@ example configuration file, building of the tests is enabled for the
>      [sparc/erc32]
>
>      [riscv/griscv]
> +
> +.. _Autoconf_migration:
this looks like something should be a cleanup separate submission.

I think the tags are usually directly translated from the section
names with camelcase?
_Migration_from_AutoconfAutomake
or so? check other docs for consistency/guidance.

>
>  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..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
> +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.
an an

> +
> +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.
> +
This needs to be updated at least to mention 2-clause BSD.

RTEMS is licensed under a combination of permissive licenses and
a modified version of the GNU General Public License (GPL).

> +`License in RTEMS
> +<https://docs.rtems.org/branches/master/eng/
> +license-requirements.html>`__
> +
> +
I think just 1 blank space?

> +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>`
> +
> +
> +
definitely not 3 blank lines though. check other docs for whitespace consistency

> +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<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
> +<https://docs.rtems.org/branches/master/c-user/task/
> +background.html#floating-point-considerations>`__

We don't like to cross-link between docs. I don't remember how this is
handled. If you can't figure it out, you'll have to ask in an email
how to link between different manuals in the docs.

> +
> +
> +How do I make a patch ?
> +--------------------------
> +
This should refer to the Software Engineering Guide.

> +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.
>      app
>      rsb-packages
>      gsoc
> +    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
>  *********************
>
> --
> 2.25.1
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel