[PATCH 1/2] Added FAQ page

Fri Apr 2 18:55:12 UTC 2021

On Fri, Apr 2, 2021 at 1:50 PM Ayushman Mishra <ayushvidushi01 at gmail.com>
wrote:

> Sir, It was given as an issue https://devel.rtems.org/ticket/3958 (
> Review wiki/TBR/Website/FAQ for correct links) for the faq page
> https://devel.rtems.org/wiki/TBR/Website/FAQ

Thanks for confirming that. When Gedare acks the patches as being
ok by him, I will see about removing that page and fixing links to it.

--joel

>
>
> On Sat, Apr 3, 2021 at 12:10 AM Joel Sherrill <joel at rtems.org> wrote:
> >
> >
> >
> > On Fri, Apr 2, 2021 at 1:19 PM Ayushman Mishra <ayushvidushi01 at gmail.com>
> wrote:
> >>
> >> Greetings Sir,
> >> I have corrected and send patches regarding FAQ page in user manual.I
> >> was able to build the page on my system and also attached a
> >> screen-shot of the builded page on browser . I have corrected
> >> whitespace consistency and reference links according to other
> >> doc-pages
> >
> >
> > Random question. Is this information from the Wiki or just an update
> > of what was already in rtems-docs? If this obsoletes any information
> > in the wiki, I would like to know so we can remove it.
> >
> >>
> >> . Regarding the issue of cross-link between docs , I had
> >> sent mail on devel mail list
> >> https://lists.rtems.org/pipermail/devel/2021-March/065882.html but
> >> haven't got any response , so few days ago after a little discussion
> >> on discord vijay sir said to post the patch and someone might point it
> >> to a better way if it exists.
> >
> >
> > I don't know if we know the answer to that with Sphinx. If "we" do, then
> > I am not part of that "we".  Hopefully someone will educate us. :)
> >
> > Gedare.. is the new patch OK? It must be in another thread because
> > I don't see it here.
> >
> > --joel
> >>
> >>
> >> On Wed, Mar 24, 2021 at 1:05 AM Gedare Bloom <gedare at rtems.org> wrote:
> >> >
> >> > 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
> >> _______________________________________________
> >> 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/128dd0d2/attachment-0001.html>