[PATCH rtems-docs v2 1/2] Added FAQ page

Fri Apr 2 21:09:00 UTC 2021

On Fri, Apr 2, 2021 at 2:26 PM Gedare Bloom <gedare at rtems.org> wrote:

> On Fri, Apr 2, 2021 at 12:19 PM Ayushman Mishra
> <ayushvidushi01 at gmail.com> wrote:
> >
> > ---
> >  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 ?
> No whitespace before punctuation. "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 happened to:
> How can I pronounce RTEMS like Joel?
>

<sarcasm> This is clearly the most important question in the FAQ <.sarcasm>

>
>
> > +What does RTEMS stand for ?
> > +-------------------------------------------------
> > +
> > +RTEMS is an an acronym for the Real-Time Executive for Multiprocessor
> Systems.
> "an an" (typo in original wiki page :)
>
> > +
> > +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>`__
> > +
>
> add the other questions even if their pages are missing, and maybe add
> a "TBD" stub or something so someone can provide the answers.
>
> Here would be "Are there Export Restrictions? on 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.).
>

This was written a LONG time ago. This should be updated to reflect the
newest
version of the POSIX standard and link to the Open Group page for it.

https://pubs.opengroup.org/onlinepubs/9699919799/

Also that 80% number should probably now be 85+% and this should reference
the POSIX Compliance Guide.

UNIX(tm) would be better. If someone knows how to insert a TM.

> +
> > +What processors is RTEMS available for ?
> > +----------------------------------------------------------
> > +
> > +:ref:`Architectures in RTEMS<TargetArchitectures>`
> Make this read as a complete sentence:
>

Probably would be good to tell people to run rtems-bsps from
the top of the source code for archtiectures and BSPs

Alternatively, use the source luke and look at
https://git.rtems.org/rtems/tree/cpukit/score/cpu

The set supported varies based on release.

> See :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>`__
> ditto
>
> > +
> > +How can I contribute?
> > +-------------------------------------------
> > +
> > +:ref:`Contributions in RTEMS<Contributing>`
> ditto
>

There should now be a good place in the users guide to send people also.

>
> > +
> > +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>`__
> ditto
>
> > +
> > +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.
> > +
> don't add extra spaces randomly
>
> > 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 at rtems.org
> > http://lists.rtems.org/mailman/listinfo/devel
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20210402/89bd7bbc/attachment-0001.html>