On Fri, Apr 2, 2021 at 2:26 PM Gedare Bloom <ged...@rtems.org> 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? > <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@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