Did you build the docs and verify they look good? On Tue, Mar 23, 2021 at 12:44 PM Ayushman Mishra <[email protected]> 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 [email protected] > + > +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 > [email protected] > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list [email protected] http://lists.rtems.org/mailman/listinfo/devel
