Sir, can you please clarify a little bit what does "each question needs to be a section heading of some level" mean , because sir I have used this "-----" line below every question which is a symbol used for showing the sentence as a heading in sphinx document and after building the questions are automatically shown as 2.10.1, 2.10.2 ... (upto total questions).
On Sun, Apr 4, 2021, 5:05 AM Chris Johns <chr...@rtems.org> wrote: > > > On 3/4/21 6:25 am, Gedare Bloom wrote: > > On Fri, Apr 2, 2021 at 12:19 PM Ayushman Mishra > > <ayushvidush...@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? > > > > > >> +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.). > >> + > >> +What processors is RTEMS available for ? > >> +---------------------------------------------------------- > >> + > >> +:ref:`Architectures in RTEMS<TargetArchitectures>` > > Make this read as a complete sentence: > > > > 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 > > > >> + > >> +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? > >> +------------------------------------------------------- > > I am not sure if anyone has said but each question needs to be a section > heading > of some level. > > >> + > >> +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. > > Please only state ELF. We do not have any COFF targets any more. > > >> 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 ? > >> > +------------------------------------------------------------------------- > >> + > > Please make sure this is MSYS2 MinGW and not MinGW. MSYS2 MinGW is > different to > MinGW. I have not looked at the original MinGW project in years. > > > >> +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. > > There should be a section on binary tools which could be referenced .... > > Does the RTEMS Project provide binary packages of tools? > > The RTEMS Project does not provide binary packages of the tools. The > project did > at one point but it found more and more resources being devoted to > providing an > ever growing number of packages for more and more operating systems and > their > variants or distributions. > > The RTEMS Project is focused on open source and providing an efficient > means to > build from source means a wide range of host system can be supported. Tools > built on a specific host are correctly matched to that system. The act of > building from source means the user has all the source code used to create > an > RTEMS tools and application present on their development system ready to be > archived for long term maintenance. > > Long term maintenance can require building of the tools years later and > the RSB > provides a portable means to build old tools on new systems. > > RTEMS Tools can be provided as binary packages externally to the project > and > there are some available. The RTEMS project encourages this but those > tools and > the support for them needs to be handled by the tools provider. > > 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@rtems.org > >> http://lists.rtems.org/mailman/listinfo/devel > > _______________________________________________ > > devel mailing list > > devel@rtems.org > > http://lists.rtems.org/mailman/listinfo/devel > > >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
