RTEMS User Manual (5.c5749d0-modified).¶

3.1.1. Users Mailing List¶

RTEMS offers a variety of support options and ways to contribute to the project. Users can ask their questions on the Users Mailing List. This is a low frequency mailing list intended for topics related to the use of RTEMS. If you are new to RTEMS, please join the list and ask whatever you want.

3.1.2. Documentation¶

You find the latest set of manuals at the Documentation Site.

3.1.3. All Mailing Lists¶

We have several mailing lists for RTEMS users and developers:

• Announce Mailing List: Announcements for major and other project-related issues.
• Bugs Mailing List: Emails generated by the Bugs Database.
• Developers Mailing List: For developers of RTEMS itself.
• Build Logs: Results from building and testing of RTEMS.
• Users Mailing List: For users of RTEMS.
• Version Control Mailing List: Commits to the RTEMS Project repositories.

3.1.4. IRC¶

RTEMS IRC is available on the Freenode network. See the Freenode web site for details on connecting, selecting a nickname, and general usage tips. If you are new to IRC it is recommended reading.

These is currently only one IRC channel available for RTEMS:

#rtems

This is a general channel for all things RTEMS. You can just hang out with other RTEMS users and developers to talk about RTEMS, using RTEMS or to make contact with other RTEMS users.

The #rtems channel is logged. You can find the logs at:

http://www.rtems.org/irclogs/

You can search the logs using Google by adding

site:rtems.org inurl:irclogs

to your search terms.

3.2.1. Search for Existing Bugs¶

You can search for existing bugs in the RTEMS Project ticket system. Please try to avoid duplicate bug reports and search for an existing bug before you report a new bug. If you are unsure, please ask on the Users Mailing List and we will help you sort it out.

3.2.2. Not RTEMS Bugs¶

Some issues appear to be an RTEMS bug to you, but are actually the intended behaviour or in the scope of other projects.

• Bugs in the assembler, the linker, or the C library (Newlib) are not RTEMS bugs. These are separate projects, with separate mailing lists and different bug reporting procedures. The RTEMS Project is happy to work with you and those projects to resolve the problem but we must work with those projects. Bugs in those products must be addressed in the corresponding project. Report assembler, linker, and GDB bugs to sourceware.org, compiler bugs to GCC, and Newlib bugs to the Newlib mailing list. If the bug was fixed, then you can update the Source Builder to pick up the fix.
• Questions about the correctness or the expected behaviour of programming language constructs or calls to library routines that are not part of RTEMS belong somewhere else.
• The POSIX standard does not specify the default set of thread attributes. Thus, when passing a NULL for attributes to pthread_create(), the application is not guaranteed any particular thread behaviour.
• The defaults for all RTEMS Application Configuration parameters are intentionally small. Thus, it is common for RTEMS tasking and file related calls to return errors indicating out of resources until the configuration parameters are properly tuned for the application. For example, there are only three file descriptors available by default: stdin, stdout, and stderr. Any attempt to open a socket or file will fail unless more file descriptors are configured.
• When first developing a BSP, many users encounter an unexpected interrupt or exception immediately upon completion of RTEMS initialization. This occurs because interrupts are disabled during RTEMS initialization and are automatically initialized as part of switching to the first task. The interrupted user code will be in either _CPU_Context_switch() or _Thread_Handler(). This indicates that an interrupt source has not been properly initialized or masked.
• Some users encounter a random reset during BSP initialization. This usually indicates that the board has a watchdog timer that is not being properly serviced during the BSP initialization.
• Bugs in releases or snapshots of RTEMS not issued by the RTEMS Project. Report them to whoever provided you with the release.

3.2.3. Good Bug Reports¶

Please open the page to submit a bug to the RTEMS Project ticket system and follow the guidelines below to write a good bug report.

• Provide a useful single line Summary.
• Use WikiFormatting to structure the information you provide. It does help the readability of the information you provide.
• Add a description of the expected behaviour. The expected behaviour may be obvious to you, but maybe not to someone else reading the bug report.
• Add a description of the actual undesired behaviour.
• Name the target hardware (processor architecture, chip family or model, and BSP) in the description.
• Add the toolchain version used (GCC, Binutils, Newlib) to the description. Custom toolchain builds are discouraged. To avoid problems caused by custom builds of the toolchain, please build your toolchain with the Source Builder. If you use a custom build of the toolchain, then try to reproduce the bug first using a toolchain built by the RSB.
• Provide the configuration options used to build the RTEMS BSP in the description. This helps to reproduce the issue.
• Make the bug reproducible by others. Write a self-contained piece of source code which can be compiled and reproduces the bug. Avoid adding assembly files (*.s) produced by the compiler, or any binary files, such as object files, executables, core files, or precompiled header files. If it is difficult or time consuming to reproduce the bug, then it may not get the attention it deserves from others. Developing and debugging real-time embedded systems can be difficult. Exercise caution in reporting an error that occurs only some of the times a certain program is executed, such that retrying a sufficient number of times results in a successful compilation; this is often a symptom of a hardware problem or application issue, not of a RTEMS bug (sorry). We do recognise that sometimes a timing bug will exist in RTEMS, but we want you to exercise due diligence before pointing fingers.
• Only when your bug report requires multiple source files to be reproduced should you attach an archive. Otherwise, the uploaded individual source file or diff should contain the minimal source code needed to reproduce the bug. In any case, make sure the above are included in the body of your bug report as plain text, even if needlessly duplicated as part of an archive.
• Please try to reproduce the bug on the current Git master. If it is not reproducible on the Git master, you should figure out if the bug was already fixed. You can search the existing bugs once again, ask on the Users Mailing List, or do a Git bisect to find a commit which fixed the bug.
• Include only information relevant to the bug.
• Write separate bug reports for different bugs.
• Select a Type for the ticket.
  • Use defect for a bug.
  • Use enhancement for a feature request in the software or an addition to the documentation.
  • Note infra is used to report issues with the RTEMS servers at OSUOSL.
• Select a Version for the ticket. This should be the first RTEMS version which is affected by this bug. If this is the current Git master branch use the version of the next release. Please provide the exact version of RTEMS in the description. If you use an RTEMS release, then the release number. If you use a Git clone, then the commit hash. The commit hash should be present in an RTEMS Project repository. Commit hashes of private branches are not interesting.
• Select a Component for the ticket. Use unspecified if you are unsure.
• Select a Severity for the ticket.
• The fields Milestone and Priority will be most likely set by an RTEMS maintainer.
• You can relate your new bug to existing bugs through the Blocked by and Blocking fields.
• If you have any external files, such as screenshots or examples, please attach these as files to the ticket. Do not use external hosting because if you do use external hosting, then our historical record is broken when those files are no longer available.
• Some fields should only be set by the maintainers, as it is not always clear what they should be set to. Feel free to make your own choices.

When you have checked that your report meets the criteria for a good bug report, please click on the Create ticket button to submit it to the RTEMS Project ticket system.

If you fail to supply enough information for a bug report to be reproduced, someone will probably ask you to post additional information. In this case, please post the additional information and not just to the person who requested it, unless explicitly told so.

3.2.4. Nobody Fixes my Bug¶

Sometimes, you may notice that after some time your bug report gets no attention and the bug is not magically fixed. This may have several reasons

• the bug report is incomplete or confusing,
• the target hardware is not available to others,
• the bug is not reproducible on the Git master,
• the bug is not reproducible at all,
• the RTEMS version is quite old and no longer used by RTEMS maintainers, or
• fixing the bug has a low priority for others.

Please note that you do not have a service contract with the RTEMS Project. The RTEMS Project is run by volunteers and persons who take care about how RTEMS performs in their application domain. If your bug does not affect the interest of someone else, then you should try to fix the bug on your own, see the Contributing guidelines. To change the priorities of others with respect to your bug, you may refer to the Commercial Support Services.

3.3.1. How to Contribute?¶

You can contribute to the RTEMS Project in various ways, for example:

• participation in mailing list discussions, helping other users
• documentation updates, clarifications, consolidation, fixes
• bug fixes, bug report consolidation
• new BSPs
• new device drivers
• new CPU (processor architecture) ports
• improvements in the existing code base (code size, code clarity, test coverage, performance optimizations)
• new features
• RTEMS Tools improvements

Most contributions will end up in patches of the RTEMS source code or documentation sources. The patch integration into the RTEMS repositories is done through a patch review process on the Developers Mailing List.

3.3.2. Preparing and Sending Patches¶

The RTEMS Project uses Git for version control. Git has a special command to prepare patches intended for mailing lists: git format-patch. Create logically connected patches as a patch series ideally accompanied by a cover letter (--cover-letter option). You can send patches via email through a Git command: git send-email.

3.3.3. Checklist for Patches¶

Check the following items before you send a patch to the Developers Mailing List:

• The author name of the patch is your full name.
• The author email of the patch is your valid email address.
• The licence conditions of the contributed content allow an integration into the RTEMS code base.
• If you are the copyright holder of the entire patch content, then please contribute it under the BSD-2-Clause license. For documentation use CC BY-SA 4.0.
• Make sure you have a pregnant subject which does not exceed 50 characters in one line. Use a “topic: The pregnant subject” style. A topic could be the main component of patch. Just have a look at existing commit messages.
• The patch has a good commit message. It should describe the reason for the change. It should list alternative approaches and why they were not chosen.
• The code changes honour the coding style. At least do your changes in the style of the surrounding code.
• The patch contains no spelling mistakes and grammar errors.
• The patch is easy to review. It changes one thing only and contains no unrelated changes. Format changes should be separated from functional changes.
• If the patch corresponds to a ticket, it should have “Close #X.” or “Update #X.” as the last line in the commit message to update status once it is committed to the repository.
• The patch builds. All RTEMS tests link with this patch.
• The patch does not introduce new compiler warnings.
• The patch does not introduce new test failures in existing tests.

3.3.4. Patch Review Process¶

Patches sent to the Developers Mailing List undergo a patch review process. Once a patch series is accepted for integration into the RTEMS code base it is committed by an RTEMS maintainer. The maintainers are usually quite busy with all sorts of stuff. If you do not get a response to a patch series submission to the mailing list after five work days, please send a reminder. It helps if you follow the Checklist for Patches. An easy to review patch series which meets the quality standards of the RTEMS Project will be more likely get integrated quickly.

RTEMS Patch Review Process.

3.3.5. Why Contribute?¶

If you are writing a major extension to RTEMS, such as a port to a new CPU family (processor architecture) or model, a new target board, a major rewrite of some existing component, or adding some missing functionality, please keep in mind the importance of keeping other developers informed. Part of being a good cooperating member of the RTEMS development team is the responsibility to consider what the other developers need in order to work effectively.

Nobody likes to do a lot of work and find it was duplicated effort. So when you work on a major new feature, you should tell Users Mailing List what you are working on, and give occasional reports of how far you have come and how confident you are that you will finish the job. This way, other developers (if they are paying attention) will be aware which projects would duplicate your effort, and can either join up with you, or at least avoid spending time on something that will be unnecessary because of your work. If, for whatever reason, you are not in a position to publicly discuss your work, please at least privately let an RTEMS maintainer know about it so they can look out for duplicated effort or possible collaborators.

You should also monitor the Users Mailing List and Developers Mailing List to see if someone else mentions working on a similar project to yours. If that happens, speak up!

If you are thinking of taking a contract to develop changes under a temporary delayed-release agreement, please negotiate the agreement so that you can give progress reports before the release date, even though you cannot release the code itself. Also please arrange so that, when the agreed-on date comes, you can release whatever part of the job you succeeded in doing, even if you have not succeeded in finishing it. Someone else may be able to finish the job.

Many people have done RTEMS ports or BSPs on their own, to a wide variety of processors, without much communication with the RTEMS development team. However, much of this work has been lost over 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.

3.3.6. 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.

4.2.1. Root Access¶

You either have root access to your host development machine or you do not. Some users are given hardware that is centrally managed. If you do not have root access you can create your work environment in your home directory. You could use a prefix of $HOME/development/rtems or $HOME/rtems. Note, the $HOME environment variable can be substituted with ~.

Choose an Installation Prefix details using Prefixes to manage the installation.

RTEMS Tools and packages do not require root access to be built and we encourage you to not build the tools as root. If you need to control write access then it is best to manage this with groups assigned to users.

If you have root access you can decide to install the tools under any suitable prefix. This may depend on the hardware in your host development machine. If the machine is a centralised build server the prefix may be used to separate production versions from the test versions and the prefix paths may have restricted access rights to only those who manage and have configuration control of the machine. We call this project sandboxing and Project Sandboxing explains this in more detail.

4.2.2. Linux¶

BSP Build will require pax package if RTEMS is configured with the --enable-tests option, see Building RTEMS Tests. This package is not installed , by default, on many Linux distributions, you can check for it using your package manager. Install it, if it is not present on your system.

A number of different Linux distrubutions are known to work. The following have been tested and report as working.

# pacman -S base-devel gdb xz unzip ncurses git zlib

# pacman -R texinfo
$ yaourt -S texinfo-legacy
# ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo

# yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git

# yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
     flex texinfo patch perl-Text-ParseWords zlib-devel

$ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
texinfo unzip ncurses-dev python-dev git

$ sudo apt-get build-dep gcc-defaults g++ gdb git unzip pax bison \
       flex libpython-dev git libncurses5-dev zlib1g-dev

$ sudo apt-get install python-dev

# sudo apt-get install zlib1g-dev

4.2.3. FreeBSD¶

The RTEMS Source Builder has been tested on FreeBSD 9.1, 10.3, 11 and 12 64bit version. You need to install some ports. They are:

# cd /usr/ports
# portinstall --batch lang/python27

If you wish to build Windows (mingw32) tools please install the following ports:

# cd /usr/ports
# portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
# portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads

The +zlip+ and +pthreads+ ports for MinGW32 are used for builiding a Windows QEMU.

If you are on FreeBSD 10.0 and you have pkgng installed you can use ‘pkg install’ rather than ‘portinstall’.

We recommend you run as root the following command to speed up Python 3’s subprocess support:

# mount -t fdescfs none /dev/fd

This speeds up closing file descriptors when creating subprocesses.

4.2.4. NetBSD¶

The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add are:

# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz

4.3.1. Mavericks¶

The RSB works on Mavericks and the GNU tools can be built for RTEMS using the Mavericks clang LLVM tool chain. You will need to build and install a couple of packages to make the RSB pass the sb-check. These are CVS and XZ. You can get these tools from a packaging tool for MacOS such as MacPorts or HomeBrew.

I do not use third-party packaging on MacOS and prefer to build the packages from source using a prefix of /usr/local. There are good third-party packages around however they sometimes bring in extra dependence and that complicates my build environment and I want to know the minimal requirements when building tools. The following are required:

. The XZ package’s home page is http://tukaani.org/xz/ and I use version

5.0.5. XZ builds and installs cleanly.

4.3.2. Sierra¶

The RSB works on Sierra with the latest Xcode.

4.4.1. Windows Path Length¶

Windows path length is limited and can cause problems when building the tools. The standard Windows API has a MAX_PATH length of 260 characters. This can effect some of the tools used by RTEMS. It is recommended you keep the top level directories as short as possible when building the RTEMS tools and you should also keep an eye on the path length when developing your application. The RTEMS built tools can handle much longer path lengths however some of the GNU tools such as those in the binutils package cannot.

The release packages of the RSB when unpacked have top level file names that are too big to build RTEMS. You need to change or rename that path to something smaller to build. This is indicated in Releases.

4.4.2. Windows Spaces In Paths¶

Occasionally, a program will fail on Windows with errors that appear as if a directory or file name was partially parsed by some utility or program. This can be caused by having directories of file names with spaces. Programs written in scripting languages sometimes fail to properly quote file names and the space is incorrectly interpreted.

Parts of the PATH inherited from the native Windows environment often include directory names with spaces. Sometimes it is necessary to set the PATH explicitly to avoid these.

4.4.3. Parallel Builds with Make¶

The MSYS2 GNU make has problems when using the jobs option. The RSB defaults to automatically using as many cores as the host machine has. To get a successful build on Windows it is recommended you add the --jobs=none option to all RSB build set commands.

4.4.4. POSIX Support¶

Building the RTEMS compilers, debugger, the RTEMS kernel and a number of other third-party packages requires a POSIX environment. On Windows you can use Cygwin or MSYS2. This document focuses on MSYS2. It is smaller than Cygwin and comes with the Arch Linux package manager pacman.

MSYS2 provides MinGW64 support as well as a POSIX shell called MSYS2. The MinGW64 compiler and related tools produce 64bit native Windows executables. The shell is a standard Bourne shell and the MSYS2 environment is a stripped Cygwin shell with enough support to run the various configure scripts needed to build the RTEMS tools and the RTEMS kernel.

MSYS2 is built around the pacman packaging tool. This makes MSYS2 a distribution and that is a welcome feature on Windows. You get a powerful tool to manage your development environment on Windows.

4.4.5. Python¶

We need Python to build the tools as the RSB is written in Python and we need suitable Python libraries to link to GDB as RTEMS makes use of GDB’s Python support. This places specific demands on the Python we need installed and available and MSYS2 provides suitable Python versions we can use. You need to make sure you have the correct type and version of Python installed.

We cannot use the Python executables created by the Python project (python.org) as they are built by Microsoft’s C (MSC) compiler. Linking the MSC Python libraries with the MinGW64 executables is not easy and MSYS provides us with a simple solution so we do not support linking MSC libraries.

MSYS2 provides two types and two versions of Python executables, MinGW and MSYS and Python version 2 and 3. For Windows we need the MinGW executable so we have suitables libraries and we have to have Python version 2 because on Windows GDB only builds with Python2.

You also need to install the MSYS version of Python along with the MinGW64 Python2 package. The MSYS Python is version 3 and the RSB can support version 2 and 3 of Python and it helps handle some of the long paths building GCC can generate.

4.4.6. MSYS2¶

MSYS2 is installed on a new machine using the MSYS2 installer found on https://msys2.github.io/. Please select the x86_64 variant for 64bit support. Run the installer following the 7 steps listed on the page.

MSYS2 uses the pacman package manager. The Arch Linux project has detailed documentation on how to use pacman. What is shown here is a just few examples of what you can do.

Open a 64bit MSYS shell from the Start Menu:

The packages we require are:

• python
• mingw-w64-x86_64-python2
• mingw-w64-x86_64-gcc
• git
• bison
• cvs
• diffutils
• make
• patch
• tar
• texinfo
• unzip

Install the packages using pacman:

$ pacman -S python mingw-w64-x86_64-python2 mingw-w64-x86_64-gcc \
bison cvs diffutils git make patch tar texinfo unzip
resolving dependencies...
looking for conflicting packages...
    .... output shortened for brevity ....

4.4.7. Cygwin¶

Building on Windows is a little more complicated because the Cygwin shell is used rather than the MSYS2 shell. The MSYS2 shell is simpler because the detected host triple is MinGW so the build is a standard cross-compiler build. A Canadian cross-build using Cygwin is supported if you would like native tools or you can use a Cygwin built set of tools.

Install a recent Cygwin version using the Cygwin setup tool. Select and install the groups and packages listed:

The setup tool will add a number of dependent package and it is ok to accept them.

Disabling Windows Defender improves performance if you have another up to date virus detection tool installed and enabled. The excellent Process Hacker 2 tool can monitor the performance and the Windows Defender service contributed a high load. In this case a third-party virus tool was installed so the Windows Defender service was not needed.

To build a MinGW tool chain a Canadian cross-compile (Cxc) is required on Cygwin because the host is Cygwin therefore a traditional cross-compile will result in Cygiwn binaries. With a Canadian cross-compile a Cygwin cross-compiler is built as well as the MinGW RTEMS cross-compiler. The Cygwin cross-compiler is required to build the C runtime for the RTEMS target because we are building under Cygiwn. The build output for an RTEMS 4.10 ARM tool set is:

chris@cygwin ~/development/rtems/src/rtems-source-builder/rtems
$ ../source-builder/sb-set-builder --log=l-arm.txt \
              --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
RTEMS Source Builder - Set Builder, v0.2
Build Set: 4.10/rtems-arm
config: expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-w64-mingw32-1
building: expat-2.1.0-x86_64-w64-mingw32-1
reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
config: tools/rtems-binutils-2.20.1-1.cfg
package: arm-rtems4.10-binutils-2.20.1-1   <1>
building: arm-rtems4.10-binutils-2.20.1-1
package: (Cxc) arm-rtems4.10-binutils-2.20.1-1   <2>
building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
reporting: tools/rtems-binutils-2.20.1-1.cfg ->
arm-rtems4.10-binutils-2.20.1-1.html
config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
config: tools/rtems-gdb-7.3.1-1.cfg
package: arm-rtems4.10-gdb-7.3.1-1
building: arm-rtems4.10-gdb-7.3.1-1
reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
config: tools/rtems-kernel-4.10.2.cfg
package: arm-rtems4.10-kernel-4.10.2-1
building: arm-rtems4.10-kernel-4.10.2-1
reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
cleaning: expat-2.1.0-x86_64-w64-mingw32-1
cleaning: arm-rtems4.10-binutils-2.20.1-1
cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
cleaning: arm-rtems4.10-gdb-7.3.1-1
cleaning: arm-rtems4.10-kernel-4.10.2-1
Build Set: Time 10:09:42.810547   <4>

5.1.1. RTEMS Tools and Kernel¶

This procedure will build a SPARC tool chain. Set up a suitable workspace to build the release in. On Unix:

$ cd
$ mkdir -p development/rtems/releases
$ cd development/rtems/releases

If building on Windows:

$ cd /c
$ mkdir -p opt/rtems
$ cd opt/rtems

Note the paths on Windows will be different to those shown.

Download the RTEMS Source Builder (RSB) from the RTEMS FTP server:

$ wget https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-source-builder-4.11.0.tar.xz
--2016-03-21 10:50:04-- https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-source-builder-4.11.0.tar.xz
Resolving ftp.rtems.org (ftp.rtems.org)... 140.211.10.151
Connecting to ftp.rtems.org (ftp.rtems.org)|140.211.10.151|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 967056 (944K) [application/x-xz]
Saving to: 'rtems-source-builder-4.11.0.tar.xz'

rtems-source-builder-4.1 100%[====================================>] 944.39K 206KB/s   in 5.5s

2016-03-21 10:50:11 (173 KB/s) - 'rtems-source-builder-4.11.0.tar.xz' saved [967056/967056]

On Unix unpack the RSB release tar file using:

$ tar Jxf rtems-source-builder-4.11.0.tar.xz
$ cd rtems-source-builder-4.11.0/rtems/

On Windows you need to shorten the path (See Windows Path Length) after you have unpacked the tar file:

$ tar Jxf rtems-source-builder-4.11.0.tar.xz
$ mv rtems-source-builder-4.11.0 4.110
$ cd 4.11.0

Build a tool chain for the SPARC architecure. We are using the SPARC architecture in our example because GDB has a good simulator that lets us run and test the samples RTEMS builds by default

If building on Windows add --jobs=none to avoid GNU make issues on Windows discussed in Parallel Builds with Make.

$ ../source-builder/sb-set-builder \
    --prefix=/opt/rtems/4.11 4.11/rtems-sparc
Build Set: 4.11/rtems-sparc
Build Set: 4.11/rtems-autotools.bset
Build Set: 4.11/rtems-autotools-internal.bset
config: tools/rtems-autoconf-2.69-1.cfg
package: autoconf-2.69-x86_64-freebsd10.1-1
Creating source directory: sources
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz
downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%)
building: autoconf-2.69-x86_64-freebsd10.1-1
config: tools/rtems-automake-1.12.6-1.cfg
package: automake-1.12.6-x86_64-freebsd10.1-1
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz
downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%)
Creating source directory: patches
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/automake-1.12.6-bugzilla.redhat.com-1239379.diff -> patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff
downloading: patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - 408.0 bytes of 408.0 bytes (100%)
building: automake-1.12.6-x86_64-freebsd10.1-1
cleaning: autoconf-2.69-x86_64-freebsd10.1-1
cleaning: automake-1.12.6-x86_64-freebsd10.1-1
Build Set: Time 0:00:32.749337
Build Set: 4.11/rtems-autotools-base.bset
config: tools/rtems-autoconf-2.69-1.cfg
package: autoconf-2.69-x86_64-freebsd10.1-1
building: autoconf-2.69-x86_64-freebsd10.1-1
reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-freebsd10.1-1.txt
reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-freebsd10.1-1.xml
config: tools/rtems-automake-1.12.6-1.cfg
package: automake-1.12.6-x86_64-freebsd10.1-1
building: automake-1.12.6-x86_64-freebsd10.1-1
reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-freebsd10.1-1.txt
reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-freebsd10.1-1.xml
installing: autoconf-2.69-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0
installing: automake-1.12.6-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0
cleaning: autoconf-2.69-x86_64-freebsd10.1-1
cleaning: automake-1.12.6-x86_64-freebsd10.1-1
Build Set: Time 0:00:15.619219
Build Set: Time 0:00:48.371085
config: devel/expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-freebsd10.1-1
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz
downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%)
building: expat-2.1.0-x86_64-freebsd10.1-1
reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-freebsd10.1-1.txt
reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-freebsd10.1-1.xml
config: tools/rtems-binutils-2.26-1.cfg
package: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/binutils-2.26.tar.bz2 -> sources/binutils-2.26.tar.bz2
downloading: sources/binutils-2.26.tar.bz2 - 24.4MB of 24.4MB (100%)
building: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1
reporting: tools/rtems-binutils-2.26-1.cfg ->
sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1.txt
reporting: tools/rtems-binutils-2.26-1.cfg ->
sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1.xml
config: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg
package: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gcc-4.9.3.tar.bz2 -> sources/gcc-4.9.3.tar.bz2
downloading: sources/gcc-4.9.3.tar.bz2 - 85.8MB of 85.8MB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/newlib-2.2.0.20150423.tar.gz -> sources/newlib-2.2.0.20150423.tar.gz
downloading: sources/newlib-2.2.0.20150423.tar.gz - 16.7MB of 16.7MB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/mpfr-3.0.1.tar.bz2 -> sources/mpfr-3.0.1.tar.bz2
downloading: sources/mpfr-3.0.1.tar.bz2 - 1.1MB of 1.1MB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/mpc-0.8.2.tar.gz -> sources/mpc-0.8.2.tar.gz
downloading: sources/mpc-0.8.2.tar.gz - 535.5kB of 535.5kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gmp-5.0.5.tar.bz2 -> sources/gmp-5.0.5.tar.bz2
downloading: sources/gmp-5.0.5.tar.bz2 - 2.0MB of 2.0MB (100%)
building: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1
reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg ->
sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1.txt
reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg ->
sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1.xml
config: tools/rtems-gdb-7.9-1.cfg
package: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-7.9.tar.xz -> sources/gdb-7.9.tar.xz
downloading: sources/gdb-7.9.tar.xz - 17.0MB of 17.0MB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch -> patches/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch
downloading: patches/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch - 1.9kB of 1.9kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch -> patches/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch
downloading: patches/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch - 827.0 bytes of 827.0 bytes (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch -> patches/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch
downloading: patches/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch - 2.6kB of 2.6kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch -> patches/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch
downloading: patches/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch - 4.9kB of 4.9kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch -> patches/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch
downloading: patches/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch - 871.0 bytes of 871.0 bytes (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch -> patches/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch
downloading: patches/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch - 5.6kB of 5.6kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch -> patches/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch
downloading: patches/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch - 1.0kB of 1.0kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch -> patches/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch
downloading: patches/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch - 3.6kB of 3.6kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch -> patches/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch
downloading: patches/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch - 1.9kB of 1.9kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch -> patches/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch
downloading: patches/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch - 16.0kB of 16.0kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch -> patches/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch
downloading: patches/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch - 14.8kB of 14.8kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch -> patches/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch
downloading: patches/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch - 3.8kB of 3.8kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0013-sim-erc32-Fix-a-few-compiler-warnings.patch-> patches/0013-sim-erc32-Fix-a-few-compiler-warnings.patch
downloading: patches/0013-sim-erc32-Fix-a-few-compiler-warnings.patch - 2.2kB of 2.2kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch -> patches/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch
downloading: patches/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch - 9.2kB of 9.2kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch -> patches/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch
downloading: patches/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch - 22.9kB of 22.9kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch -> patches/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch
downloading: patches/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch - 1.5kB of 1.5kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch -> patches/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch
downloading: patches/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch - 5.8kB of 5.8kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch -> patches/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch
downloading: patches/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch - 66.7kB of 66.7kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch -> patches/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch
downloading: patches/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch - 26.1kB of 26.1kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0020-sim-erc32-Updated-documentation.patch -> patches/0020-sim-erc32-Updated-documentation.patch
downloading: patches/0020-sim-erc32-Updated-documentation.patch - 16.1kB of 16.1kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0021-sim-erc32-Add-data-watchpoint-support.patch -> patches/0021-sim-erc32-Add-data-watchpoint-support.patch
downloading: patches/0021-sim-erc32-Add-data-watchpoint-support.patch - 10.1kB of 10.1kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch -> patches/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch
downloading: patches/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch - 25.5kB of 25.5kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch -> patches/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch
downloading: patches/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch - 1.3kB of 1.3kB (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-sim-arange-inline.diff -> patches/gdb-sim-arange-inline.diff
downloading: patches/gdb-sim-arange-inline.diff - 761.0 bytes of 761.0 bytes (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-sim-cgen-inline.diff -> patches/gdb-sim-cgen-inline.diff
downloading: patches/gdb-sim-cgen-inline.diff - 706.0 bytes of 706.0 bytes (100%)
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/patch-gdb-python-python-config.py -> patches/patch-gdb-python-python-config.py
downloading: patches/patch-gdb-python-python-config.py - 449.0 bytes of 449.0 bytes (100%)
building: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1
reporting: tools/rtems-gdb-7.9-1.cfg ->
sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1.txt
reporting: tools/rtems-gdb-7.9-1.cfg ->
sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1.xml
config: tools/rtems-tools-4.11-1.cfg
package: rtems-tools-4.11.0-1
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-tools-4.11.0.tar.xz -> sources/rtems-tools-4.11.0.tar.xz
downloading: sources/rtems-tools-4.11.0.tar.xz - 1.6MB of 1.6MB (100%)
building: rtems-tools-4.11.0-1
reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11.0-1.txt
reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11.0-1.xml
config: tools/rtems-kernel-4.11.cfg
package: sparc-rtems4.11-kernel-4.11.0-1
download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-4.11.0.tar.xz -> sources/rtems-4.11.0.tar.xz
downloading: sources/rtems-4.11.0.tar.xz - 9.3MB of 9.3MB (100%)
building: sparc-rtems4.11-kernel-4.11.0-1
reporting: tools/rtems-kernel-4.11.cfg -> sparc-rtems4.11-kernel-4.11.0-1.txt
reporting: tools/rtems-kernel-4.11.cfg -> sparc-rtems4.11-kernel-4.11.0-1.xml
installing: expat-2.1.0-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0
installing: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0
installing: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0
installing: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0
installing: rtems-tools-4.11.0-1 -> /opt/work/rtems/4.11.0
installing: sparc-rtems4.11-kernel-4.11.0-1 -> /opt/work/rtems/4.11.0
cleaning: expat-2.1.0-x86_64-freebsd10.1-1
cleaning: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1
cleaning: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1
cleaning: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1
cleaning: rtems-tools-4.11.0-1
cleaning: sparc-rtems4.11-kernel-4.11.0-1
Build Set: Time 0:19:15.713662

You can now build a third-party library or an application as defaulted in TBD.

5.2.1. POSIX and OS X Host Tools Chain¶

This procedure will build a SPARC tool chain.

Clone the RTEMS Source Builder (RSB) repository:

$ cd
$ mkdir -p development/rtems
$ cd development/rtems
$ git clone git://git.rtems.org/rtems-source-builder.git rsb
Cloning into 'rsb'...
remote: Counting objects: 5837, done.
remote: Compressing objects: 100% (2304/2304), done.
remote: Total 5837 (delta 4014), reused 5056 (delta 3494)
Receiving objects: 100% (5837/5837), 2.48 MiB | 292.00 KiB/s, done.
Resolving deltas: 100% (4014/4014), done.
Checking connectivity... done.

Check all the host packages you need are present. Current libraries are not checked and this includes checking for the python development libraries GDB requires:

$ cd rsb
$ ./source-builder/sb-check
RTEMS Source Builder - Check, 5 (089327b5dcf9)
Environment is ok

If you are unsure how to specify the build set for the architecture you wish to build, just ask the tool:

$ ../source-builder/sb-set-builder --list-bsets   <1>
RTEMS Source Builder - Set Builder, v4.11.0
Examining: config
Examining: ../source-builder/config    <2>
    4.10/rtems-all.bset      <3>
    4.10/rtems-arm.bset      <4>
    4.10/rtems-autotools.bset
    4.10/rtems-avr.bset
    4.10/rtems-bfin.bset
    4.10/rtems-h8300.bset
    4.10/rtems-i386.bset
    4.10/rtems-lm32.bset
    4.10/rtems-m32c.bset
    4.10/rtems-m32r.bset
    4.10/rtems-m68k.bset
    4.10/rtems-mips.bset
    4.10/rtems-nios2.bset
    4.10/rtems-powerpc.bset
    4.10/rtems-sh.bset
    4.10/rtems-sparc.bset
    4.11/rtems-all.bset
    4.11/rtems-arm.bset
    4.11/rtems-autotools.bset
    4.11/rtems-avr.bset
    4.11/rtems-bfin.bset
    4.11/rtems-h8300.bset
    4.11/rtems-i386.bset
    4.11/rtems-lm32.bset
    4.11/rtems-m32c.bset
    4.11/rtems-m32r.bset
    4.11/rtems-m68k.bset
    4.11/rtems-microblaze.bset
    4.11/rtems-mips.bset
    4.11/rtems-moxie.bset
    4.11/rtems-nios2.bset
    4.11/rtems-powerpc.bset
    4.11/rtems-sh.bset
    4.11/rtems-sparc.bset
    4.11/rtems-sparc64.bset
    4.11/rtems-v850.bset
    4.9/rtems-all.bset
    4.9/rtems-arm.bset
    4.9/rtems-autotools.bset
    4.9/rtems-i386.bset
    4.9/rtems-m68k.bset
    4.9/rtems-mips.bset
    4.9/rtems-powerpc.bset
    4.9/rtems-sparc.bset
    gnu-tools-4.6.bset
    rtems-4.10-base.bset    <5>
    rtems-4.11-base.bset
    rtems-4.9-base.bset
    rtems-base.bset         <5>

Build a tool chain for the SPARC architecture. We are using the SPARC architecture because GDB has a good simulator that lets us run and test the samples RTEMS builds by default. The current development version is 5 and is on master:

$ cd rtems
$ ../source-builder/sb-set-builder --prefix=/usr/home/chris/development/rtems/5 5/rtems-sparc
RTEMS Source Builder - Set Builder, 5 (089327b5dcf9)
Build Set: 5/rtems-sparc
Build Set: 5/rtems-autotools.bset
Build Set: 5/rtems-autotools-internal.bset
config: tools/rtems-autoconf-2.69-1.cfg
package: autoconf-2.69-x86_64-linux-gnu-1
Creating source directory: sources
download: ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz
downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%)
building: autoconf-2.69-x86_64-linux-gnu-1
config: tools/rtems-automake-1.12.6-1.cfg
package: automake-1.12.6-x86_64-linux-gnu-1
download: ftp://ftp.gnu.org/gnu/automake/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz
downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%)
Creating source directory: patches
download: https://git.rtems.org/rtems-tools/plain/tools/5/automake/automake-1.12.6-bugzilla.redhat.com-1239379.diff -> patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff
downloading: patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - 408.0 bytes of 408.0 bytes (100%)
building: automake-1.12.6-x86_64-linux-gnu-1
cleaning: autoconf-2.69-x86_64-linux-gnu-1
cleaning: automake-1.12.6-x86_64-linux-gnu-1
Build Set: Time 0:00:12.713221
Build Set: 5/rtems-autotools-base.bset
config: tools/rtems-autoconf-2.69-1.cfg
package: autoconf-2.69-x86_64-linux-gnu-1
building: autoconf-2.69-x86_64-linux-gnu-1
reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-linux-gnu-1.txt
reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-linux-gnu-1.xml
config: tools/rtems-automake-1.12.6-1.cfg
package: automake-1.12.6-x86_64-linux-gnu-1
building: automake-1.12.6-x86_64-linux-gnu-1
reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-linux-gnu-1.txt
reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-linux-gnu-1.xml
installing: autoconf-2.69-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5
installing: automake-1.12.6-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5
cleaning: autoconf-2.69-x86_64-linux-gnu-1
cleaning: automake-1.12.6-x86_64-linux-gnu-1
Build Set: Time 0:00:09.105363
Build Set: Time 0:00:21.822083
config: devel/expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-linux-gnu-1
download: http://downloads.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz
 redirect: https://vorboss.dl.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz
downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%)
building: expat-2.1.0-x86_64-linux-gnu-1
reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-linux-gnu-1.txt
reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-linux-gnu-1.xml
config: tools/rtems-binutils-2.29-1.cfg
package: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1
download: ftp://ftp.gnu.org/gnu/binutils/binutils-2.29.tar.bz2 -> sources/binutils-2.29.tar.bz2
downloading: sources/binutils-2.29.tar.bz2 - 27.7MB of 27.7MB (100%)
download: https://devel.rtems.org/raw-attachment/ticket/3091/0001-Fix-Binutils-2.29-PR21884.patch -> patches/0001-Fix-Binutils-2.29-PR21884.patch
downloading: patches/0001-Fix-Binutils-2.29-PR21884.patch - 8.8kB of 8.8kB (100%)
building: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1
reporting: tools/rtems-binutils-2.29-1.cfg -> sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1.txt
reporting: tools/rtems-binutils-2.29-1.cfg -> sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1.xml
config: tools/rtems-gcc-7.2.0-newlib-2.5.0.20170922-1.cfg
package: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1
download: https://ftp.gnu.org/gnu/gcc/gcc-7.2.0/gcc-7.2.0.tar.xz -> sources/gcc-7.2.0.tar.xz
downloading: sources/gcc-7.2.0.tar.xz - 59.4MB of 59.4MB (100%)
download: https://gcc.gnu.org/git/?p=gcc.git;a=commitdiff_plain;h=62ffbcb7502f0ff88ff7566cd6d7c59c0483ecc0 -> patches/gcc-62ffbcb7502f0ff88ff7566cd6d7c59c0483ecc0.patch
downloading: patches/gcc-62ffbcb7502f0ff88ff7566cd6d7c59c0483ecc0.patch - 1.8kB
download: https://gcc.gnu.org/git/?p=gcc.git;a=blobdiff_plain;f=gcc/config.gcc;h=593631849bb5e0df5cc4ff42c1a1cc34b7eec2f8;hp=a9196cd26d9ec24c2e3f6026f63348cae3734861;hb=e840389000b8339a63bee56d8b3...<see log> -> patches/gcc-593631849bb5e0df5cc4ff42c1a1cc34b7eec2f8.patch
downloading: patches/gcc-593631849bb5e0df5cc4ff42c1a1cc34b7eec2f8.patch - 806.0 bytes
download: https://gcc.gnu.org/git/?p=gcc.git;a=blobdiff_plain;f=gcc/config/rs6000/rtems.h;h=7ea9ebdb77b6a9b7060ad2362318e0e12b9058ae;hp=8a62fdcbaf321d616021c4c396619b7f56cf5ed2;hb=e840389000b8339a...<see log> -> patches/gcc-7ea9ebdb77b6a9b7060ad2362318e0e12b9058ae.patch
downloading: patches/gcc-7ea9ebdb77b6a9b7060ad2362318e0e12b9058ae.patch - 3.2kB
download: ftp://sourceware.org/pub/newlib/newlib-2.5.0.20170922.tar.gz -> sources/newlib-2.5.0.20170922.tar.gz
downloading: sources/newlib-2.5.0.20170922.tar.gz - 17.3MB of 17.3MB (100%)
download: https://devel.rtems.org/raw-attachment/ticket/2514/0001-RTEMS-Self-contained-POSIX-objects.patch -> patches/0001-RTEMS-Self-contained-POSIX-objects.patch
downloading: patches/0001-RTEMS-Self-contained-POSIX-objects.patch - 5.7kB of 5.7kB (100%)
download: https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=patch;h=c165a27c0147471977377acd8918ab3b446f947a -> patches/newlib-cygwin-git-c165a27c0147471977377acd8918ab3b446f947a.patch
downloading: patches/newlib-cygwin-git-c165a27c0147471977377acd8918ab3b446f947a.patch - 986.0 bytes
download: https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=patch;h=ce189d8afef720b0977b5cae7f9eabf5d49b530c -> patches/newlib-cygwin-git-ce189d8afef720b0977b5cae7f9eabf5d49b530c.patch
downloading: patches/newlib-cygwin-git-ce189d8afef720b0977b5cae7f9eabf5d49b530c.patch - 3.4kB
download: https://ftp.gnu.org/gnu/mpfr/mpfr-3.1.4.tar.bz2 -> sources/mpfr-3.1.4.tar.bz2
downloading: sources/mpfr-3.1.4.tar.bz2 - 1.2MB of 1.2MB (100%)
download: https://ftp.gnu.org/gnu/mpc/mpc-1.0.3.tar.gz -> sources/mpc-1.0.3.tar.gz
downloading: sources/mpc-1.0.3.tar.gz - 654.2kB of 654.2kB (100%)
download: https://ftp.gnu.org/gnu/gmp/gmp-6.1.0.tar.bz2 -> sources/gmp-6.1.0.tar.bz2
downloading: sources/gmp-6.1.0.tar.bz2 - 2.3MB of 2.3MB (100%)
building: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1
reporting: tools/rtems-gcc-7.2.0-newlib-2.5.0.20170922-1.cfg -> sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1.txt
reporting: tools/rtems-gcc-7.2.0-newlib-2.5.0.20170922-1.cfg -> sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1.xml
config: tools/rtems-gdb-8.0.1-1.cfg
package: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1
download: http://ftp.gnu.org/gnu/gdb/gdb-8.0.1.tar.xz -> sources/gdb-8.0.1.tar.xz
downloading: sources/gdb-8.0.1.tar.xz - 18.7MB of 18.7MB (100%)
download: https://gaisler.org/gdb/gdb-8.0.1-sis-leon2-leon3.diff -> patches/gdb-8.0.1-sis-leon2-leon3.diff
downloading: patches/gdb-8.0.1-sis-leon2-leon3.diff - 224.5kB of 224.5kB (100%)
building: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1
reporting: tools/rtems-gdb-8.0.1-1.cfg -> sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1.txt
reporting: tools/rtems-gdb-8.0.1-1.cfg -> sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1.xml
config: tools/rtems-tools-5-1.cfg
package: rtems-tools-HEAD-1
Creating source directory: sources/git
git: clone: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git
git: reset: git://git.rtems.org/rtems-tools.git
git: fetch: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git
git: checkout: git://git.rtems.org/rtems-tools.git => HEAD
git: pull: git://git.rtems.org/rtems-tools.git
building: rtems-tools-HEAD-1
reporting: tools/rtems-tools-5-1.cfg -> rtems-tools-HEAD-1.txt
reporting: tools/rtems-tools-5-1.cfg -> rtems-tools-HEAD-1.xml
config: tools/rtems-kernel-5.cfg
package: sparc-rtems5-kernel-5-1
building: sparc-rtems5-kernel-5-1
reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-5-1.txt
reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-5-1.xml
installing: expat-2.1.0-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5
installing: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5
installing: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5
installing: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5
installing: rtems-tools-HEAD-1 -> /usr/home/chris/development/rtems/5
installing: sparc-rtems5-kernel-5-1 -> /usr/home/chris/development/rtems/5
cleaning: expat-2.1.0-x86_64-linux-gnu-1
cleaning: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1
cleaning: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1
cleaning: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1
cleaning: rtems-tools-HEAD-1
cleaning: sparc-rtems5-kernel-5-1
Build Set: Time 0:39:33.988995

5.2.2. Windows Host Tool Chain¶

This section details how you create an RTEMS development environment on Windows. The installation documented here is on Windows 7 64bit Professional. Building on Windows 10 has been reported as working.

Please see Microsoft Windows before continuing.

 ~
$ mkdir -p /c/opt/rtems

 ~
$ cd /c/opt/rtems
 /c/opt/rtems
$ git clone git://git.rtems.org/rtems-source-builder.git rsb
Cloning into 'rsb'...
remote: Counting objects: 5716, done.
remote: Compressing objects: 100% (2183/2183), done.
remote: Total 5716 (delta 3919), reused 5071 (delta 3494)
Receiving objects: 100% (5716/5716), 2.46 MiB | 656.00 KiB/s, done.
Resolving deltas: 100% (3919/3919), done.
Checking connectivity... done.
Checking out files: 100% (630/630), done.
 /c/opt/rtems
$ cd rsb

 /c/opt/rtems/rsb
$ git checkout 4.11
Branch 4.11 set up to track remote branch 4.11 from origin.
Switched to a new branch '4.11'
 /c/opt/rtems/rsb
$

 /c/opt/rtems/rsb
$ cd rtems
 /c/opt/rtems/rsb/rtems
$ ../source-builder/sb-check
RTEMS Source Builder - Check, 4.11 (01ac76f2f90f)
Environment is ok
 /c/opt/rtems/rsb/rtems
$

 /c/opt/rtems/rsb/rtems
$ ../source-builder/sb-set-builder --prefix=/c/opt/rtems/4.11 \
                                   --jobs=none 4.11/rtems-i386
RTEMS Source Builder - Set Builder, 4.11 (01ac76f2f90f)
Build Set: 4.11/rtems-i386
Build Set: 4.11/rtems-autotools.bset
Build Set: 4.11/rtems-autotools-internal.bset
config: tools/rtems-autoconf-2.69-1.cfg
package: autoconf-2.69-x86_64-w64-mingw32-1
Creating source directory: sources
download: ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz
downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%)
 building: autoconf-2.69-x86_64-w64-mingw32-1
config: tools/rtems-automake-1.12.6-1.cfg
package: automake-1.12.6-x86_64-w64-mingw32-1
download: ftp://ftp.gnu.org/gnu/automake/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz
downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%)
 building: automake-1.12.6-x86_64-w64-mingw32-1
cleaning: autoconf-2.69-x86_64-w64-mingw32-1
cleaning: automake-1.12.6-x86_64-w64-mingw32-1
Build Set: Time 0:00:42.515625
Build Set: 4.11/rtems-autotools-base.bset
config: tools/rtems-autoconf-2.69-1.cfg
package: autoconf-2.69-x86_64-w64-mingw32-1
building: autoconf-2.69-x86_64-w64-mingw32-1
reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-w64-mingw32-1.txt
reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-w64-mingw32-1.xml
config: tools/rtems-automake-1.12.6-1.cfg
package: automake-1.12.6-x86_64-w64-mingw32-1
building: automake-1.12.6-x86_64-w64-mingw32-1
reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-w64-mingw32-1.txt
reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-w64-mingw32-1.xml
tarball: tar/rtems-4.11-autotools-x86_64-w64-mingw32-1.tar.bz2
installing: autoconf-2.69-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11
installing: automake-1.12.6-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11
cleaning: autoconf-2.69-x86_64-w64-mingw32-1
cleaning: automake-1.12.6-x86_64-w64-mingw32-1
Build Set: Time 0:00:37.718750
Build Set: Time 0:01:20.234375
config: devel/expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-w64-mingw32-1
download: http://downloads.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz
 redirect: http://iweb.dl.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz
downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%)
building: expat-2.1.0-x86_64-w64-mingw32-1
reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.txt
reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.xml
config: tools/rtems-binutils-2.24-1.cfg
package: i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1
download: ftp://ftp.gnu.org/gnu/binutils/binutils-2.24.tar.bz2 -> sources/binutils-2.24.tar.bz2
downloading: sources/binutils-2.24.tar.bz2 - 21.7MB of 21.7MB (100%)
building: i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1
reporting: tools/rtems-binutils-2.24-1.cfg -> i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1.txt
reporting: tools/rtems-binutils-2.24-1.cfg -> i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1.xml
config: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg
package: i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1
download: ftp://ftp.gnu.org/gnu/gcc/gcc-4.9.3/gcc-4.9.3.tar.bz2 -> sources/gcc-4.9.3.tar.bz2
downloading: sources/gcc-4.9.3.tar.bz2 - 85.8MB of 85.8MB (100%)
download: ftp://sourceware.org/pub/newlib/newlib-2.2.0.20150423.tar.gz -> sources/newlib-2.2.0.20150423.tar.gz
downloading: sources/newlib-2.2.0.20150423.tar.gz - 16.7MB of 16.7MB (100%)
download: http://www.mpfr.org/mpfr-3.0.1/mpfr-3.0.1.tar.bz2 -> sources/mpfr-3.0.1.tar.bz2
downloading: sources/mpfr-3.0.1.tar.bz2 - 1.1MB of 1.1MB (100%)
download: http://www.multiprecision.org/mpc/download/mpc-0.8.2.tar.gz -> sources/mpc-0.8.2.tar.gz
downloading: sources/mpc-0.8.2.tar.gz - 535.5kB of 535.5kB (100%)
download: ftp://ftp.gnu.org/gnu/gmp/gmp-5.0.5.tar.bz2 -> sources/gmp-5.0.5.tar.bz2
downloading: sources/gmp-5.0.5.tar.bz2 - 2.0MB of 2.0MB (100%)
building: i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1
reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg ->
i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1.txt
reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg ->
i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1.xml
config: tools/rtems-gdb-7.9-1.cfg
package: i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1
download: http://ftp.gnu.org/gnu/gdb/gdb-7.9.tar.xz -> sources/gdb-7.9.tar.xz
downloading: sources/gdb-7.9.tar.xz - 17.0MB of 17.0MB (100%)
download: https://git.rtems.org/rtems-tools/plain/tools/4.11/gdb/gdb-sim-arange-inline.diff -> patches/gdb-sim-arange-inline.diff
downloading: patches/gdb-sim-arange-inline.diff - 761.0 bytes of 761.0 bytes (100%)
download: https://git.rtems.org/rtems-tools/plain/tools/4.11/gdb/gdb-sim-cgen-inline.diff -> patches/gdb-sim-cgen-inline.diff
downloading: patches/gdb-sim-cgen-inline.diff - 706.0 bytes of 706.0 bytes (100%)
building: i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1
reporting: tools/rtems-gdb-7.9-1.cfg ->
i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1.txt
reporting: tools/rtems-gdb-7.9-1.cfg ->
i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1.xml
config: tools/rtems-tools-4.11-1.cfg
package: rtems-tools-4.11-1
Creating source directory: sources/git
git: clone: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git
git: reset: git://git.rtems.org/rtems-tools.git
git: fetch: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git
git: checkout: git://git.rtems.org/rtems-tools.git => 4.11
git: pull: git://git.rtems.org/rtems-tools.git
building: rtems-tools-4.11-1
reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11-1.txt
reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11-1.xml
config: tools/rtems-kernel-4.11.cfg
installing: expat-2.1.0-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11
installing: i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11
installing: i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11
installing: i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11
installing: rtems-tools-4.11-1 -> C:\opt\rtems\4.11
cleaning: expat-2.1.0-x86_64-w64-mingw32-1
cleaning: i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1
cleaning: i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1
cleaning: i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1
cleaning: rtems-tools-4.11-1
Build Set: Time 1:32:58.972919
 /c/opt/rtems/rsb/rtems
$

 /c
$ cd /c/opt/rtems
 /c/opt/rtems
$ export PATH=/c/opt/rtems/4.11/bin:$PATH
 /c/opt/rtems
$

 /c/opt/rtems
$ mkdir kernel
 /c/opt/rtems
$ cd kernel
 /c/opt/rtems/kernel
$ git clone git://git.rtems.org/rtems.git rtems
Cloning into 'rtems'...
remote: Counting objects: 482766, done.
remote: Compressing objects: 100% (88781/88781), done.
remote: Total 482766 (delta 389610), reused 475155 (delta 383437)
Receiving objects: 100% (482766/482766), 69.77 MiB | 697.00 KiB/s, done.
Resolving deltas: 100% (389610/389610), done.
Checking connectivity... done.
Checking out files: 100% (10626/10626), done.
 /c/opt/rtems/kernel
$ cd rtems
 /c/opt/rtems/kernel/rtems
$ git checkout 4.11
Checking out files: 100% (2553/2553), done.
Branch 4.11 set up to track remote branch 4.11 from origin.
Switched to a new branch '4.11'
 /c/opt/rtems/kernel
$

 /c/opt/rtems/kernel/rtems
$ ./bootstrap -c
removing automake generated Makefile.in files
removing configure files
removing aclocal.m4 files

 /c/opt/rtems/kernel/rtems
$ ./bootstrap -p
Generating ./c/src/ada/preinstall.am
Generating ./c/src/lib/libbsp/arm/altera-cyclone-v/preinstall.am
Generating ./c/src/lib/libbsp/arm/atsam/preinstall.am
Generating ./c/src/lib/libbsp/arm/beagle/preinstall.am
Generating ./c/src/lib/libbsp/arm/csb336/preinstall.am
Generating ./c/src/lib/libbsp/arm/csb337/preinstall.am
Generating ./c/src/lib/libbsp/arm/edb7312/preinstall.am
Generating ./c/src/lib/libbsp/arm/gdbarmsim/preinstall.am
  .......
Generating ./cpukit/score/cpu/mips/preinstall.am
Generating ./cpukit/score/cpu/moxie/preinstall.am
Generating ./cpukit/score/cpu/nios2/preinstall.am
Generating ./cpukit/score/cpu/no_cpu/preinstall.am
Generating ./cpukit/score/cpu/or1k/preinstall.am
Generating ./cpukit/score/cpu/powerpc/preinstall.am
Generating ./cpukit/score/cpu/sh/preinstall.am
Generating ./cpukit/score/cpu/sparc/preinstall.am
Generating ./cpukit/score/cpu/sparc64/preinstall.am
Generating ./cpukit/score/cpu/v850/preinstall.am
Generating ./cpukit/score/preinstall.am
Generating ./cpukit/telnetd/preinstall.am
Generating ./cpukit/wrapup/preinstall.am
Generating ./cpukit/zlib/preinstall.am
 /c/opt/rtems/kernel/rtems

$ /c/opt/rtems/rsb/source-builder/sb-bootstrap
RTEMS Source Builder - RTEMS Bootstrap, 4.11 (76188ee494dd)
  1/139: autoreconf: configure.ac
  2/139: autoreconf: c/configure.ac
  3/139: autoreconf: c/src/configure.ac
  4/139: autoreconf: c/src/ada-tests/configure.ac
  5/139: autoreconf: c/src/lib/libbsp/arm/configure.ac
  6/139: autoreconf: c/src/lib/libbsp/arm/altera-cyclone-v/configure.ac
  7/139: autoreconf: c/src/lib/libbsp/arm/atsam/configure.ac
  8/139: autoreconf: c/src/lib/libbsp/arm/beagle/configure.ac
  9/139: autoreconf: c/src/lib/libbsp/arm/csb336/configure.ac
 10/139: autoreconf: c/src/lib/libbsp/arm/csb337/configure.ac
 11/139: autoreconf: c/src/lib/libbsp/arm/edb7312/configure.ac
  .......
129/139: autoreconf: testsuites/samples/configure.ac
130/139: autoreconf: testsuites/smptests/configure.ac
131/139: autoreconf: testsuites/sptests/configure.ac
132/139: autoreconf: testsuites/tmtests/configure.ac
133/139: autoreconf: testsuites/tools/configure.ac
134/139: autoreconf: testsuites/tools/generic/configure.ac
135/139: autoreconf: tools/build/configure.ac
136/139: autoreconf: tools/cpu/configure.ac
137/139: autoreconf: tools/cpu/generic/configure.ac
138/139: autoreconf: tools/cpu/nios2/configure.ac
139/139: autoreconf: tools/cpu/sh/configure.ac
Bootstrap time: 0:20:38.759766
 /c/opt/rtems/kernel/rtems
$

 /c/opt/rtems/kernel/rtems
$ cd ..
 /c/opt/rtems/kernel
$ mkdir pc686
 /c/opt/rtems/kernel
$ cd pc686
 /c/opt/rtems/kernel/pc686
$

 /c/opt/rtems/kernel/pc686
$ /c/opt/rtems/kernel/rtems/configure --prefix=/c/opt/rtems/4.11 \
       --target=i386-rtems4.11 --disable-networking --enable-rtemsbsp=pc686
checking for gmake... no
checking for make... make
checking for RTEMS Version... 4.11.99.0
checking build system type... x86_64-pc-mingw64
checking host system type... x86_64-pc-mingw64
checking target system type... i386-pc-rtems4.11
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
checking whether to enable maintainer-specific portions of Makefiles... no
checking that generated files are newer than configure... done
configure: creating ./config.status
configure: configuring in ./tools/build
  .......
checking whether make sets $(MAKE)... yes
checking whether to enable maintainer-specific portions of Makefiles... no
checking that generated files are newer than configure... done
configure: creating ./config.status
config.status: creating Makefile

target architecture: i386.
available BSPs: pc686.
'make all' will build the following BSPs: pc686.
other BSPs can be built with 'make RTEMS_BSP="bsp1 bsp2 ..."'

config.status: creating Makefile
 /c/opt/rtems/kernel/pc686
$

 /c/opt/rtems/kernel/pc686
$ make
Making all in tools/build
make[1]: Entering directory '/c/opt/rtems/kernel/pc686/tools/build'
make  all-am
make[2]: Entering directory '/c/opt/rtems/kernel/pc686/tools/build'
gcc -DHAVE_CONFIG_H -I. -I/c/opt/rtems/kernel/rtems/tools/build     -g -O2 -MT
cklength.o -MD -MP -MF .deps/cklength.Tpo -c -o cklength.o
/c/opt/rtems/kernel/rtems/tools/build/cklength.c
gcc -DHAVE_CONFIG_H -I. -I/c/opt/rtems/kernel/rtems/tools/build     -g -O2 -MT
eolstrip.o -MD -MP -MF .deps/eolstrip.Tpo -c -o eolstrip.o
/c/opt/rtems/kernel/rtems/tools/build/eolstrip.c
  ..........
i386-rtems4.11-objcopy -O binary nsecs.nxe nsecs.bin
../../../../../pc686/build-tools/bin2boot -v nsecs.ralf 0x00097E00
../../../../../pc686/lib/start16.bin 0x00097C00 0 nsecs.bin 0x00100000 0
header address       0x00097e00, its memory size 0xzx
first  image address 0x00097c00, its memory size 0x00000200
second image address 0x00100000, its memory size 0x0003d800
rm -f nsecs.nxe
make[6]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites/samples/nsecs'
make[5]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites/samples'
make[4]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites/samples'
make[4]: Entering directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites'
make[4]: Nothing to be done for 'all-am'.
make[4]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites'
make[3]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites'
make[2]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686'
make[1]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c'
make[1]: Entering directory '/c/opt/rtems/kernel/pc686'
make[1]: Nothing to be done for 'all-am'.
make[1]: Leaving directory '/c/opt/rtems/kernel/pc686'
 /c/opt/rtems/kernel/pc696
$

$ make install
Making install in tools/build
make[1]: Entering directory '/c/opt/rtems/kernel/pc686/tools/build'
make[2]: Entering directory '/c/opt/rtems/kernel/pc686/tools/build'
 /usr/bin/mkdir -p '/c/opt/rtems/4.11/bin'
  /usr/bin/install -c cklength.exe eolstrip.exe packhex.exe unhex.exe
  rtems-bin2c.exe '/c/opt/rtems/4.11/bin'
 /usr/bin/mkdir -p '/c/opt/rtems/4.11/bin'
 /usr/bin/install -c install-if-change '/c/opt/rtems/4.11/bin'
make[2]: Nothing to be done for 'install-data-am'.
make[2]: Leaving directory '/c/opt/rtems/kernel/pc686/tools/build'
make[1]: Leaving directory '/c/opt/rtems/kernel/pc686/tools/build'
Making install in tools/cpu
make[1]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu'
Making install in generic
make[2]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu/generic'
make[3]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu/generic'
make[3]: Nothing to be done for 'install-exec-am'.
make[3]: Nothing to be done for 'install-data-am'.
make[3]: Leaving directory '/c/opt/rtems/kernel/pc686/tools/cpu/generic'
make[2]: Leaving directory '/c/opt/rtems/kernel/pc686/tools/cpu/generic'
make[2]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu'
make[3]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu'
make[3]: Nothing to be done for 'install-exec-am'.
make[3]: Nothing to be done for 'install-data-am'.
  ..........
make[2]: Entering directory '/c/opt/rtems/kernel/pc686'
make[2]: Nothing to be done for 'install-exec-am'.
 /usr/bin/mkdir -p '/c/opt/rtems/4.11/make'
 /usr/bin/install -c -m 644 /c/opt/rtems/kernel/rtems/make/main.cfg
 /c/opt/rtems/kernel/rtems/make/leaf.cfg '/c/opt/rtems/4.11/make'
 /usr/bin/mkdir -p '/c/opt/rtems/4.11/share/rtems4.11/make/Templates'
 /usr/bin/install -c -m 644
 /c/opt/rtems/kernel/rtems/make/Templates/Makefile.dir
 /c/opt/rtems/kernel/rtems/make/Templates/Makefile.leaf
 /c/opt/rtems/kernel/rtems/make/Templates/Makefile.lib
 '/c/opt/rtems/4.11/share/rtems4.11/make/Templates'
 /usr/bin/mkdir -p '/c/opt/rtems/4.11/make/custom'
 /usr/bin/install -c -m 644 /c/opt/rtems/kernel/rtems/make/custom/default.cfg
 '/c/opt/rtems/4.11/make/custom'
make[2]: Leaving directory '/c/opt/rtems/kernel/pc686'
make[1]: Leaving directory '/c/opt/rtems/kernel/pc686'
 /c/opt/rtems/kernel/pc686
$

5.3.1. Development Sources¶

Create a new location to build the RTEMS kernel:

$ cd
$ cd development/rtems
$ mkdir kernel
$ cd kernel

Clone the RTEMS respository:

$ git clone git://git.rtems.org/rtems.git rtems
Cloning into 'rtems'...
remote: Counting objects: 483342, done.
remote: Compressing objects: 100% (88974/88974), done.
remote: Total 483342 (delta 390053), reused 475669 (delta 383809)
Receiving objects: 100% (483342/483342), 69.88 MiB | 1.37 MiB/s, done.
Resolving deltas: 100% (390053/390053), done.
Checking connectivity... done.

5.3.2. Tools Path Set Up¶

We need to set our path to include the RTEMS tools we built in the previous section. The RTEMS tools needs to be first in your path because RTEMS provides specific versions of the autoconf and automake tools. We want to use the RTEMS version and not your host’s versions:

$ export PATH=$HOME/development/rtems/5/bin:$PATH

5.3.3. Bootstrapping¶

The developers version of the code from git requires we bootstrap the source code. This is an autoconf and automake bootstrap to create the various files generated by autoconf and automake. RTEMS does not keep these generated files under version control. The bootstrap process is slow so to speed it up the RSB provides a command that can perform the bootstrap in parallel using your available cores. We need to enter the cloned source directory then run the bootstrap commands:

$ cd rtems
$ ./bootstrap -c && $HOME/development/rtems/rsb/source-builder/sb-bootstrap
removing automake generated Makefile.in files
removing configure files
removing aclocal.m4 files
RTEMS Source Builder - RTEMS Bootstrap, 5 (089327b5dcf9)
  1/139: autoreconf: configure.ac
  2/139: autoreconf: cpukit/configure.ac
  3/139: autoreconf: tools/cpu/configure.ac
  4/139: autoreconf: tools/cpu/generic/configure.ac
  5/139: autoreconf: tools/cpu/sh/configure.ac
  6/139: autoreconf: tools/cpu/nios2/configure.ac
  7/139: autoreconf: tools/build/configure.ac
  8/139: autoreconf: doc/configure.ac
 ......
124/139: autoreconf: c/src/make/configure.ac
125/139: autoreconf: c/src/librtems++/configure.ac
126/139: autoreconf: c/src/ada-tests/configure.ac
127/139: autoreconf: testsuites/configure.ac
128/139: autoreconf: testsuites/libtests/configure.ac
129/139: autoreconf: testsuites/mptests/configure.ac
130/139: autoreconf: testsuites/fstests/configure.ac
131/139: autoreconf: testsuites/sptests/configure.ac
132/139: autoreconf: testsuites/tmtests/configure.ac
133/139: autoreconf: testsuites/smptests/configure.ac
134/139: autoreconf: testsuites/tools/configure.ac
135/139: autoreconf: testsuites/tools/generic/configure.ac
136/139: autoreconf: testsuites/psxtests/configure.ac
137/139: autoreconf: testsuites/psxtmtests/configure.ac
138/139: autoreconf: testsuites/rhealstone/configure.ac
139/139: autoreconf: testsuites/samples/configure.ac
Bootstrap time: 0:02:47.398824

5.3.4. Building a BSP¶

We build RTEMS in a directory outside of the source tree we have just cloned and bootstrapped. You cannot build RTEMS while in the source tree. Lets create a suitable directory using the name of the BSP we are going to build:

$ cd ..
$ mkdir erc32
$ cd erc32

Configure RTEMS using the configure command. We use a full path to configure so the object files built contain the absolute path of the source files. If you are source level debugging you will be able to access the source code to RTEMS from the debugger. We will build for the erc32 BSP with POSIX enabled and the networking stack disabled:

$ $HOME/development/rtems/kernel/rtems/configure --prefix=$HOME/development/rtems/5 \
                   --target=sparc-rtems5 --enable-rtemsbsp=erc32 --enable-posix \
                   --disable-networking
checking for gmake... no
checking for make... make
checking for RTEMS Version... 4.11.99.0
checking build system type... x86_64-pc-linux-gnu
checking host system type... x86_64-pc-linux-gnu
checking target system type... sparc-unknown-rtems5
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking whether to enable maintainer-specific portions of Makefiles... no
checking that generated files are newer than configure... done
 ......
checking target system type... sparc-unknown-rtems5
checking rtems target cpu... sparc
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for sparc-rtems5-strip... sparc-rtems5-strip
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking whether to enable maintainer-specific portions of Makefiles... no
checking that generated files are newer than configure... done
configure: creating ./config.status
config.status: creating Makefile

target architecture: sparc.
available BSPs: erc32.
'make all' will build the following BSPs: erc32.
other BSPs can be built with 'make RTEMS_BSP="bsp1 bsp2 ..."'

config.status: creating Makefile

Build RTEMS using two cores:

$ make -j 2
Making all in tools/build
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build'
make  all-am
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build'
gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT cklength.o -MD -MP -MF .deps/cklength.Tpo -c -o cklength.o /home/chris/development/rtems/kernel/rtems/tools/build/cklength.c
gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT eolstrip.o -MD -MP -MF .deps/eolstrip.Tpo -c -o eolstrip.o /home/chris/development/rtems/kernel/rtems/tools/build/eolstrip.c
mv -f .deps/cklength.Tpo .deps/cklength.Po
mv -f .deps/eolstrip.Tpo .deps/eolstrip.Po
gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT compat.o -MD -MP -MF .deps/compat.Tpo -c -o compat.o /home/chris/development/rtems/kernel/rtems/tools/build/compat.c
gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT packhex.o -MD -MP -MF .deps/packhex.Tpo -c -o packhex.o /home/chris/development/rtems/kernel/rtems/tools/build/packhex.c
mv -f .deps/compat.Tpo .deps/compat.Po
gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT unhex.o -MD -MP -MF .deps/unhex.Tpo -c -o unhex.o /home/chris/development/rtems/kernel/rtems/tools/build/unhex.c
mv -f .deps/packhex.Tpo .deps/packhex.Po
gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT rtems-bin2c.o -MD -MP -MF .deps/rtems-bin2c.Tpo -c -o rtems-bin2c.o /home/chris/development/rtems/kernel/rtems/tools/build/rtems-bin2c.c
mv -f .deps/unhex.Tpo .deps/unhex.Po
gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT binpatch.o -MD -MP -MF .deps/binpatch.Tpo -c -o binpatch.o /home/chris/development/rtems/kernel/rtems/tools/build/binpatch.c
mv -f .deps/rtems-bin2c.Tpo .deps/rtems-bin2c.Po
gcc  -g -O2   -o cklength cklength.o
mv -f .deps/binpatch.Tpo .deps/binpatch.Po
gcc  -g -O2   -o eolstrip eolstrip.o compat.o
gcc  -g -O2   -o packhex packhex.o
gcc  -g -O2   -o rtems-bin2c rtems-bin2c.o compat.o
gcc  -g -O2   -o unhex unhex.o compat.o
gcc  -g -O2   -o binpatch binpatch.o
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build'
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build'
Making all in tools/cpu
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
Making all in generic
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
make[2]: Nothing to be done for 'all'.
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
make[2]: Nothing to be done for 'all-am'.
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
Making all in testsuites/tools
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools'
Making all in generic
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools/generic'
make[2]: Nothing to be done for 'all'.
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools/generic'
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools'
make[2]: Nothing to be done for 'all-am'.
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools'
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools'
Making all in sparc-rtems5/c
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c'
Making all in .
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c'
Configuring RTEMS_BSP=erc32
checking for gmake... no
checking for make... make
checking build system type... x86_64-pc-linux-gnu
checking host system type... sparc-unknown-rtems5
 ......
sparc-rtems5-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs -I.. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/../support/include   -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -MT init.o -MD -MP -MF .deps/init.Tpo -c -o init.o /home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs/init.c
sparc-rtems5-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs -I.. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/../support/include   -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -MT empty.o -MD -MP -MF .deps/empty.Tpo -c -o empty.o /home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs/empty.c
mv -f .deps/empty.Tpo .deps/empty.Po
mv -f .deps/init.Tpo .deps/init.Po
sparc-rtems5-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections  -mcpu=cypress   -o nsecs.exe init.o empty.o
sparc-rtems5-nm -g -n nsecs.exe > nsecs.num
sparc-rtems5-size nsecs.exe
   text    data     bss     dec     hex filename
 121392    1888    6624  129904   1fb70 nsecs.exe
cp nsecs.exe nsecs.ralf
make[6]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites/samples/nsecs'
make[5]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites/samples'
make[4]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites/samples'
make[4]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites'
make[4]: Nothing to be done for 'all-am'.
make[4]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites'
make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites'
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32'
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c'
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32'
make[1]: Nothing to be done for 'all-am'.
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32'

5.3.5. Installing A BSP¶

All that remains to be done is to install the kernel. Installing RTEMS copies the API headers and architecture specific libraries to a locaiton under the prefix you provide. You can install any number of BSPs under the same prefix. We recommend you have a separate prefix for different versions of RTEMS. Do not mix versions of RTEMS under the same prefix. Make installs RTEMS with the following command:

$ make install
Making install in tools/build
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build'
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build'
/bin/mkdir -p '/home/chris/development/rtems/5/bin'
/usr/bin/install -c cklength eolstrip packhex unhex rtems-bin2c '/home/chris/development/rtems/5/bin'
/bin/mkdir -p '/home/chris/development/rtems/5/bin'
/usr/bin/install -c install-if-change '/home/chris/development/rtems/5/bin'
make[2]: Nothing to be done for 'install-data-am'.
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build'
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build'
Making install in tools/cpu
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
Making install in generic
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
make[3]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
make[3]: Nothing to be done for 'install-exec-am'.
make[3]: Nothing to be done for 'install-data-am'.
make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
make[3]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
make[3]: Nothing to be done for 'install-exec-am'.
make[3]: Nothing to be done for 'install-data-am'.
make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
  ....
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c'
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32'
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32'
make[2]: Nothing to be done for 'install-exec-am'.
/bin/mkdir -p '/home/chris/development/rtems/5/make'
/usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/main.cfg /home/chris/development/rtems/kernel/rtems/make/leaf.cfg '/home/chris/development/rtems/5/make'
/bin/mkdir -p '/home/chris/development/rtems/5/share/rtems5/make/Templates'
/usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.dir /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.leaf /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.lib '/home/chris/development/rtems/5/share/rtems5/make/Templates'
/bin/mkdir -p '/home/chris/development/rtems/5/make/custom'
/usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/custom/default.cfg '/home/chris/development/rtems/5/make/custom'
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32'
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32'

5.3.6. Contributing Patches¶

RTEMS welcomes fixes to bugs and new features. The RTEMS Project likes to have bugs fixed against a ticket created on our Developer Site. Please raise a ticket if you have a bug. Any changes that are made can be tracked against the ticket. If you want to add a new a feature please post a message to Developers Mailing List describing what you would like to implement. The RTEMS maintainer will help decide if the feature is in the best interest of the project. Not everything is and the maintainers need to evalulate how much effort it is to maintain the feature. Once accepted into the source tree it becomes the responsibility of the maintainers to keep the feature updated and working.

Changes to the source tree are tracked using git. If you have not made changes and enter the source tree and enter a git status command you will see nothing has changed:

$ cd ../rtems
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

We will make a change to the source code. In this example I change the help message to the RTEMS shell’s halt command. Running the same git status command reports:

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   cpukit/libmisc/shell/main_halt.c

no changes added to commit (use "git add" and/or "git commit -a")

As an example I have a ticket open and the ticket number is 9876. I commit the change with the follow git command:

$ git commit cpukit/libmisc/shell/main_halt.c

An editor is opened and I enter my commit message. The first line is a title and the following lines form a body. My message is:

shell: Add more help detail to the halt command.

Closes #9876.

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# Explicit paths specified without -i or -o; assuming --only paths...
#
# Committer: Chris Johns <chrisj@rtems.org>
#
# On branch master
# Your branch is up-to-date with 'origin/master'.
#
# Changes to be committed:
#       modified:   cpukit/libmisc/shell/main_halt.c

When you save and exit the editor git will report the commit’s status:

$ git commit cpukit/libmisc/shell/main_halt.c
[master 9f44dc9] shell: Add more help detail to the halt command.
 1 file changed, 1 insertion(+), 1 deletion(-)

You can either email the patch to Developers Mailing List with the following git command, and it is minus one on the command line:

$ git send-email --to=devel@rtems.org -1
 <add output here>

Or you can ask git to create a patch file using:

$ git format-patch -1
0001-shell-Add-more-help-detail-to-the-halt-command.patch

This patch can be attached to a ticket.

7.2.1. altera-cyclone-v (Intel Cyclone V)¶

This BSP offers only one variant, the altcycv_devkit. This variant supports the Intel Cyclone V system on chip. The basic hardware initialization is not performed by the BSP. A boot loader with device tree support must be used to start the BSP, e.g. U-Boot.

The BSP is known to run on these boards:

• Cyclone V SoC Development Kit
• Enclustra Mars MA3 SoC Module
• Terasic DE10-Standard Development Kit

arm-rtems5-objcopy -O binary app.exe app.bin
gzip -9 -f -c app.bin > app.bin.gz
mkimage -A arm -O linux -T kernel -a 0x00300000 -e 0x00300000 -n RTEMS -d app.bin.gz app.img

tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset

7.2.2. atsam¶

TODO.

7.2.3. beagle¶

This BSP supports four variants, beagleboardorig, beagleboardxm, beaglebonewhite and beagleboneblack. The basic hardware initialization is not performed by the BSP. A boot loader with device tree support must be used to start the BSP, e.g., U-Boot.

TODO(These drivers are present but not documented yet):

• Clock driver.
• Network Interface Driver.
• SDcard driver.
• GPIO Driver.
• Console driver.
• PWM Driver.
• RTC driver.

arm-rtems5-objcopy hello.exe -O binary app.bin
gzip -9 app.bin
mkimage -A arm -O linux -T kernel -a 0x80000000 -e 0x80000000 -n RTEMS -d app.bin.gz rtems-app.img

setenv bootdelay 5
uenvcmd=run boot
boot=fatload mmc 0 0x80800000 rtems-app.img ; fatload mmc 0 0x88000000 am335x-boneblack.dtb ; bootm 0x80800000 - 0x88000000

int am335x_i2c_bus_register(
const char         *bus_path,
uintptr_t           register_base,
uint32_t            input_clock,
rtems_vector_number irq
);

rtems_status_code bsp_register_spi(
   const char         *bus_path,
   uintptr_t           register_base,
   rtems_vector_number irq
);

7.2.4. csb336¶

TODO.

7.2.5. edb7312¶

TODO.

7.2.6. gdbarmsim¶

TODO.

7.2.7. gumstix¶

TODO.

7.2.8. imx (NXP i.MX)¶

This BSP offers only one variant, the imx7. This variant supports the i.MX 7Dual processor. The basic hardware initialization is not performed by the BSP. A boot loader with device tree support must be used to start the BSP, e.g. U-Boot.

arm-rtems5-objcopy -O binary app.exe app.bin
gzip -9 -f -c app.bin > app.bin.gz
mkimage -A arm -O linux -T kernel -a 0x80200000 -e 0x80200000 -n RTEMS -d app.bin.gz app.img

tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset

#include <assert.h>
#include <bsp.h>

void i2c_init(void)
{
  int rv;

  rv = i2c_bus_register_imx("/dev/i2c-0", "i2c0");
  assert(rv == 0);
}

#include <assert.h>
#include <bsp.h>

void spi_init(void)
{
  int rv;

  rv =  spi_bus_register_imx("/dev/spi-0", "spi0");
  assert(rv == 0);
}

7.2.9. lm3s69xx¶

TODO.

7.2.10. lpc176x¶

TODO.

7.2.11. imx (NXP i.MX)¶

This BSP offers only one variant, the imx7. This variant supports the i.MX 7Dual processor. The basic hardware initialization is not performed by the BSP. A boot loader with device tree support must be used to start the BSP, e.g. U-Boot.

arm-rtems5-objcopy -O binary app.exe app.bin
gzip -9 -f -c app.bin > app.bin.gz
mkimage -A arm -O linux -T kernel -a 0x80200000 -e 0x80200000 -n RTEMS -d app.bin.gz app.img

tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset

#include <assert.h>
#include <bsp.h>

void i2c_init(void)
{
  int rv;

  rv = i2c_bus_register_imx("/dev/i2c-0", "i2c0");
  assert(rv == 0);
}

#include <assert.h>
#include <bsp.h>

void spi_init(void)
{
  int rv;

  rv =  spi_bus_register_imx("/dev/spi-0", "spi0");
  assert(rv == 0);
}

7.2.12. raspberrypi¶

TODO.

7.2.13. realview-pbx-a9¶

TODO.

7.2.14. rtl22xx¶

TODO.

7.2.15. smdk2410¶

TODO.

7.2.16. tms570¶

TODO.

7.2.17. xilinx-zynq¶

TODO.

7.3.1. bf537Stamp¶

TODO.

7.3.2. eZKit533¶

TODO.

7.3.3. TLL6527M¶

TODO.

7.4.1. epiphany_sim¶

TODO.

7.5.1. pc386¶

TODO.

7.6.1. lm32_evr¶

TODO.

7.6.2. milkymist¶

TODO.

7.7.1. av5282¶

TODO.

7.7.2. csb360¶

TODO.

7.7.3. gen68340¶

TODO.

7.7.4. gen68360¶

TODO.

7.7.5. genmcf548x¶

TODO.

7.7.6. mcf5206elite¶

TODO.

7.7.7. mcf52235¶

TODO.

7.7.8. mcf5225x¶

TODO.

7.7.9. mcf5235¶

TODO.

7.7.10. mcf5329¶

TODO.

7.7.11. mrm332¶

TODO.

7.7.12. mvme147¶

TODO.

7.7.13. mvme147s¶

TODO.

7.7.14. mvme162¶

TODO.

7.7.15. mvme167¶

TODO.

7.7.16. uC5282¶

TODO.

7.9.1. csb350¶

TODO.

7.9.2. hurricane¶

TODO.

7.9.3. jmr3904¶

TODO.

7.9.4. malta¶

TODO.

7.9.5. rbtx4925¶

TODO.

7.9.6. rbtx4938¶

TODO.

7.10.1. moxiesim¶

TODO.

7.11.1. nios2_iss¶

TODO.

7.12.1. generic_or1k¶

TODO.

7.13.1. beatnik¶

TODO.

7.13.2. gen5200¶

TODO.

7.13.3. gen83xx¶

TODO.

7.13.4. haleakala¶

TODO.

7.13.5. motorola_powerpc¶

powerpc-rtems5-objcopy -O binary -R .comment -S ticker.exe rtems
gzip -9 -f rtems
powerpc-rtems5-ld -o ticker.boot bootloader.o --just-symbols=ticker.exe -b binary rtems.gz -T ppcboot.lds -no-warn-mismatch
powerpc-rtems5-objcopy -O binary ticker.boot ticker.bin

7.13.6. mpc55xxevb¶

TODO.

7.13.7. mpc8260ads¶

TODO.

7.13.8. mvme3100¶

TODO.

7.13.9. mvme5500¶

TODO.

7.13.10. psim¶

TODO.

7.13.11. qemuppc¶

TODO.

7.13.12. qoriq (QorIQ)¶

The BSP for the QorIQ chip family offers three variants. The qoriq_e500 variant supports the P-series chips such as P1020, P2010 and P2020. The qoriq_e6500_32 (32-bit ISA) and qoriq_e6500_64 (64-bit ISA) variants support the T-series chips such as T2080 and T4240. The basic hardware initialization is not performed by the BSP. A boot loader with device tree support must be used to start the BSP, e.g. U-Boot.

The BSP is known to run on these boards:

• NXP P1020RDB
• MicroSys miriac MPX2020 (System on Module)
• Artesyn MVME2500 (VME64x SBC)
• NXP T2080RDB
• NXP T4240RDB
• MEN G52A (CompactPCI Serial)

The qoriq_core_0 and qoriq_core_1 variants should be used with care. They are inteded for a RTEMS_MULTIPROCESSING configuration on the P1020.

powerpc-rtems5-objcopy -O binary app.exe app.bin
gzip -9 -f -c app.bin > app.bin.gz
mkimage -A ppc -O linux -T kernel -a 0x4000 -e 0x4000 -n RTEMS -d app.bin.gz app.img

tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset

../configure --enable-rtemsbsp=qoriq_e6500_32 \
    QORIQ_IS_HYPERVISOR_GUEST=1 \
    QORIQ_UART_0_ENABLE=0 \
    QORIQ_UART_1_ENABLE=0 \
    QORIQ_TLB1_ENTRY_COUNT=16

7.13.13. ss555¶

TODO.

7.13.14. t32mppc¶

TODO.

7.13.15. tqm8xx¶

TODO.

7.13.16. virtex¶

TODO.

7.13.17. virtex4¶

TODO.

7.13.18. virtex5¶

TODO.

7.14.1. riscv¶

This BSP offers 13 variants:

• rv32i
• rv32iac
• rv32im
• rv32imac
• rv32imafc
• rv32imafd
• rv32imafdc
• rv64imac
• rv64imac_medany
• rv64imafd
• rv64imafd_medany
• rv64imafdc
• rv64imafdc_medany

Each variant corresponds to a GCC multilib. A particular variant reflects an ISA with ABI and code model choice.

The basic hardware initialization is not performed by the BSP. A boot loader with device tree support must be used to start the BSP, e.g. BBL. The BSP must be started im machine mode.

The reference platform for this BSP is the Qemu virt machine.

7.14.2. griscv¶

This RISC-V BSP supports chips using the GRLIB.

7.15.1. gensh1¶

TODO.

7.15.2. gensh2¶

TODO.

7.15.3. gensh4¶

TODO.

7.15.4. shsim¶

TODO.

7.16.1. niagara¶

TODO.

7.16.2. usiii¶

TODO.

7.17.1. erc32¶

TODO.

7.17.2. leon2¶

TODO.

7.17.3. leon3¶

TODO.

7.18.1. gdbv850sim¶

TODO.

7.19.1. amd64¶

This BSP offers only one variant, amd64. The BSP can run on UEFI-capable systems by using FreeBSD’s bootloader, which then loads the RTEMS executable (an ELF image).

Currently only the console driver and context initialization and switching are functional (to a bare minimum), but this is enough to run the hello.exe sample in the RTEMS testsuite.

$ git clone git://github.com/tianocore/edk2.git
$ cd edk2
$ make -C BaseTools
$ . edksetup.sh

ACTIVE_PLATFORM       = OvmfPkg/OvmfPkgX64.dsc
TARGET                = DEBUG
TARGET_ARCH           = X64
# You can use GCC46 as well, if you'd prefer
TOOL_CHAIN_TAG        = GCC5

$ find . -name "*.fd"
./Build/OvmfX64/DEBUG_GCC5/FV/MEMFD.fd
./Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd # the file we're looking for
./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_CODE.fd
./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_VARS.fd

$ qemu-img create freebsd.img 8G
$ OVMF_LOCATION=/path/to/ovmf/OVMF.fd
$ FREEBSD_MEMSTICK=/path/to/FreeBSD-11.2-amd64-memstick.img
$ qemu-system-x86_64 -m 1024 -serial stdio --bios $OVMF_LOCATION \
    -drive format=raw,file=freebsd.img \
    -drive format=raw,file=$FREEBSD_MEMSTICK

# Upload hello.exe anywhere accessible within the host
$ curl --upload-file hello.exe https://transfer.sh/rtems

# Back the FreeBSD kernel up
$ cp -r /boot/kernel/ /boot/kernel.old
# Bring networking online if it isn't already
$ dhclient em0
# You may need to add the --no-verify-peer depending on your server
$ fetch https://host.com/path/to/rtems/hello.exe
# Replace default kernel
$ cp hello.exe /boot/kernel/kernel
$ reboot

8.2.1. Machine Flags and ABI¶

All code in an RTEMS executable must be built with the same machine flags. The machine flags control the instruction set and application binary interface (ABI) the compiler generates. As the executable is statically linked all code must use the same instruction set the hardware is configured to support and all code must conform to the same ABI. Any variation can result in unpredictable behavior such as crashes, failures or lock ups. It is recommend an executable is built with the same or equivalent tool set. Mixing of tool set versions can also result in undefined behavior. The RTEMS tool rtems-execinfo can audit an RTEMS executable and list the machine flags and compilers used.

RTEMS by default does not support instruction emulation for unsupported instructions. RTEMS applications are normally built from source so binary compatibility is not as important as performance. Instruction emulation is costly to execute and rebuilding the executable with the correct instruction set only needs to be done once.

8.5.1. System Initialization Handlers¶

RTEMS supports the automatic registration of services used in applications. This method of initialization automatically configures RTEMS with only the services used in an application. There is no manual configuration of services used and no updating of initialization function tables.

RTEMS uses specialized sections in the ELF executable to perform this task. The system is based on the FreeBSD SYSINT Framework. Ordered initialization is performed before multitasking is started.

The RTEMS Tool rtems-exeinfo can provide some detail about the registered handlers. The following shows the initialization handlers for the hello world sample application in the RTEMS kernel’s testsuite:

.. code-block:: none

$ rtems-exeinfo –init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe RTEMS Executable Info 5.5416cfa39dd6 $ rtems-exeinfo –init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe exe: arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe

Compilation:

Producers: 2

GNU AS 2.31.1: 14 objects

GNU C11 7.3.0 20180125 (RTEMS 5, RSB e55769c64cf1a201588565a5662deafe3f1ccdcc, Newlib 103b055035fea328f8bc7826801760fb1c055683): 284 objects

Common flags: 4

-march=armv7-a -mthumb -mfpu=neon -mfloat-abi=hard

Init sections: 2

.init_array

0x001047c1 frame_dummy

.rtemsroset

0x00104c05 bsp_work_area_initialize 0x00104c41 bsp_start 0x0010eb45 zynq_debug_console_init 0x0010ec19 rtems_counter_sysinit 0x0010b779 _User_extensions_Handler_initialization 0x0010c66d rtems_initialize_data_structures 0x00107751 _RTEMS_tasks_Manager_initialization 0x0010d4f5 _POSIX_Keys_Manager_initialization 0x0010dd09 _Thread_Create_idle 0x0010cf01 rtems_libio_init 0x001053a5 rtems_filesystem_initialize 0x0010546d _Console_simple_Initialize 0x0010c715 _IO_Initialize_all_drivers 0x001076d5 _RTEMS_tasks_Initialize_user_tasks_body 0x0010cfa9 rtems_libio_post_driver

The section .rtemsroset lists the handlers called in order. The handlers can be split into the BSP initialization handlers that start the BSP:

• bsp_work_area_initialize
• bsp_start
• zynq_debug_console_init
• rtems_counter_sysinit

And the remainder are handlers for services used by the application. The list varies based on the services the application uses.

8.7.1. System Design¶

The use of dynamic loading in a project is a system design decision. Some systems will have strict requirements where loading code into a live system is not allowed while other projects will benefit from the system level flexibility dynamically loading code provides.

Code loaded at run time needs to be resident or accessible to the target via RTEMS’s file system. Targets that have suitable media or a network interface to NFS servers to hold the executable object and library files are best suited.

Dynamically loading code uses more memory than statically linking the same code into the base image. The link editor maintains symbol tables where each symbol is a string, an address, and some additional data. The executable object files resident in memory each have data to manage them, the memory they use, and any dependencies they might have. The link editor is designed to minimize the memory overheads however only statically linked executables have no memory overhead.

The link editor relocates the code and data into RAM fixing it to the load address as it is loaded. A target needs to have suitably configured memory available for the executable object file to reside in. The memory must be able to support read, write and executable type access. Fine control of the memory and it’s modes can be supported using a customer allocator. Examples are systems that have a custom memory map, specialized memory for the execution of code or a requirement for read-only executable sections.

The load address of an executable object file is determined by the load order and the allocator used. The default allocator for the link editor is the system heap which means the location a specific executable object file is loaded at depends on the memory allocated before it is loaded and when in the load order it is loaded. A statically linked executable’s address map is fixed and this is considered important in some systems. A dynamically loaded system can be loaded in a repeatable manner if the load order is the same and the initialization sequence of the system is controlled. A custom allocator may also help.

Management of dynamically loadable object files and libraries adds to the configuration management of the hosts in a project. The loadable files need to be released and tracked in a suitable configuration management process just like the base image is. Executable object files and libraries are specific to a version of RTEMS and cannot be mixed or moved and this needs to be carefully managed. Currently there are no checks an executable object file matches the version of the base image it is being loaded on. These extra configuration controlled items add to the overheads of a project and need to be considered.

Dynamically loadable systems have a number of features that benefit some systems and products. Systems can be built on a base of trusted or golden modules. A number of projects using a common base of hardware can make use of proven modules reducing the testing and qualification overhead for each new release. A tested base image with libraries for common and available boards provides a simple and fast way for new users to trial and use RTEMS.

A project can use dynamic loading during development, shipping statically linked executables in production. Hardware used by a development team can have more memory, extra media for disk drives, or a network interface.

8.7.2. Loader Interface¶

Run-time executable object file loading and management is via the standard’s based calls provided by the header file <dlfcn.h>. The details of the calls follow.

void* dlopen(const char* path, int mode);

The dlopen() function makes the symbols (function identifiers and data object identifiers) in the executable object file specified by file available to the calling program.

The executable object files eligible for this operation are in the ELF format.

The link loader may load embedded dependencies in executable object files. In such cases, a dlopen() operation may load those dependencies in addition to the executable object file specified by file.

A successful dlopen() returns a handle which the caller may use on subsequent calls to dlsym(), dlinfo() and dlclose().

The value of the handle should not be interpreted in any way by the caller.

Subsequent calls to dlopen() for the same executable object file increases the references to it.

The file argument is used to construct a pathname to the executable object file or archive library of executable object files. If the file argument contains a colon (:) the name of the executable object file in the library follows and this file name may optionally end with @ followed by a number which is the absolute offset in the library file where the executable object file starts. If an executable object file is not detected at the offset the archive library’s file table is searched.

If file is a null pointer, dlopen() returns a global symbol table handle. This handle provides access to the global symbols from an ordered set of executable object files consisting of the original base image file, the set of executable object files loaded using dlopen() operations with the RTLD_GLOBAL flag, and any dependencies loaded. As the latter sets of executable object files can change during execution, the set of symbols made available by this handle can also change dynamically.

Only a single copy of an executable object file is brought into the address space, even if dlopen() is invoked multiple times in reference to the executable object file, and even if different pathnames are used to reference the executable object file.

Unresolved external symbols do not cause an error to be returned allowing the loading of jointly dependent executable object files.

If dlopen() fails, it returns a null pointer, and sets an error condition which may be interrogated with dlerror().

The mode parameter describes how dlopen() operates upon file with respect to the processing of relocations and the scope of visibility of the symbols provided within file. When an executable object file is brought into the address space, it may contain references to symbols whose addresses are not known until the executable object file is loaded.

If a loaded executable object file and any dependent executable object files loaded with it contain any initialiser functions, they are called in the order loaded before dlopen() returns.

The modes RTLD_LAZY and RTLD_NOW do not effect the type of relocation performed, it is same for both modes. All relocations of an executable object file and any dependent executable object files loaded with it are completed before the dlopen() call returns. The execution performance of the code loaded can be considered deterministic once dlopen() has returned.

Any executable object file loaded by dlopen() can reference global symbols in the base image, any executable object files loaded included in the same dlopen() invocation, and any executable object files that were loaded in any dlopen() invocation and which specified the RTLD_GLOBAL flag. To determine the scope of visibility for the symbols loaded with a dlopen() invocation, the mode parameter should be a bitwise-inclusive OR with one of the following values:

RTLD_GLOBAL

The executable object file’s symbols are made available for relocation processing of any other executable object file. In addition, symbol lookup using dlopen(NULL,mode) and an associated dlsym() allows executable object files loaded with this mode to be searched.

RTLD_LOCAL

The executable object file’s symbols shall not be made available for relocation processing of any other executable object files.

If neither RTLD_GLOBAL nor RTLD_LOCAL is specified, the default behavior is unspecified.

If RTLD_GLOBAL has been specified, the executable object file maintains it’s RTLD_GLOBAL status regardless of any previous or future specification of RTLD_LOCAL, as long as the executable object file remains in the address space.

Symbols introduced through calls to dlopen() may be used in relocation activities. Symbols that duplicate symbols already defined by the base image or previous dlopen() calls are treated as an error and the object file is not loaded. Symbols introduced through loading dependent executable object files are ignored or not loaded depending on the method used to build the executable object files.

The symbols introduced by dlopen() operations and available through dlsym() are at a minimum those which are exported as identifiers of global scope by the executable object file. Typically, such identifiers shall be those that were specified in (for example) C source code as having extern linkage.

int dlclose(void* handle);

Releases a reference to the executable object file referenced by handle. If the reference count drops to 0, the executable object file’s global symbol table is made unavailable. When all references to the global symbols the executable object file provided have been removed the object file is removed from the address space.

If the executable object being removed has any termination routines in it they are called.

void* dlsym(void* handle, const char* symbol);

The dlsym() function obtains the address of a symbol (a function identifier or a data object identifier) defined in the symbol table identified by the handle argument. The handle argument is a symbol table handle returned from a call to dlopen() (and which has not since been released by a call to dlclose()), and name is the symbol’s name as a character string. The return value from dlsym(), cast to a pointer to the type of the named symbol, can be used to call (in the case of a function) or access the contents of (in the case of a data object) the named symbol.

The dlsym() function searches for the named symbol in the symbol table referenced by handle and returns the address of the code or data location specified by the null-terminated character string symbol. Which libraries and objects are searched depends on the handle parameter.

Upon successful completion, if name names a function identifier, dlsym() returns the address of the function converted from type pointer to function to type pointer to void; otherwise, dlsym() shall return the address of the data object associated with the data object identifier named by name converted from a pointer to the type of the data object to a pointer to void. If handle does not refer to a valid symbol table handle or if the symbol named by name cannot be found in the symbol table associated with handle, dlsym() shall return a null pointer.

int dlinfo(void* handle, int request, void* args);

The dlinfo() function provides information about dynamically loaded object. The action taken by dlinfo() and exact meaning and type of the argument args depend on value of the request argument provided by the caller.

RTLD_DI_UNRESOLVED

Return 1 in an indexer value pointed to by args if the symbol table handle has unresolved relocation records to symbols. If the handle is the global symbol table handle or RTLD_SELF return 1 if any unresolved relocation records to symbols are present in any loaded executable object files..

const char *dlerror(void);

The dlerror() function returns a null-terminated character string (with no trailing <newline>) that describes the last error that occurred during dynamic linking processing. If no dynamic linking errors have occurred since the last invocation of dlerror(), dlerror() returns NULL. Thus, invoking dlerror() a second time, immediately following a prior invocation, results in NULL being returned.

This example opens an object file, checks for any unresolved symbols the object file may have, locates a global symbol in the object file, calls it then closes the object file:

#include <stdbool.h>
#include <stdio.h>
#include <dlfcn.h>

typedef int (*call_sig)(void);

bool load_object (void)
{
  void*    handle;
  call_sig call;
  int      unresolved;

  handle = dlopen ("/code.o", RTLD_NOW | RTLD_GLOBAL);
  if (handle == NULL)
  {
    printf ("dlopen failed: %s\n", dlerror ());
    return false;
  }

  if (dlinfo (handle, RTLD_DI_UNRESOLVED, &unresolved) < 0)
  {
    printf ("dlinfo failed: %s\n", dlerror ());
    dlclose (handle);
    return false;
  }

  if (unresolved != 0)
  {
    printf ("object.o has unresolved external symbols\n");
    dlclose (handle);
    return false;
  }

  call = dlsym (handle, "foo");
  if (call == NULL)
  {
    printf("dlsym failed: symbol 'foo' not found\n");
    dlclose (handle);
    return false;
  }

  printf ("'foo()' returns: %i\n", call ());

  if (dlclose (handle) < 0)
  {
    printf("dlclose failed: %s\n", dlerror());
    return false;
  }

  return true;
}

8.7.3. Symbols¶

The RTEMS link editor manages the symbols for the base image and all resident executable object files. A symbol is an identifier string and a pointer value to a function identifier or a data object identifier. The symbols held in the symbol tables are used in the relocation of executable object files or they can be accessed by application code using the dlsym() call.

An executable object file’s symbols are removed from the global symbol table when it is closed or orphaned. An executale object file cannot be unloaded if a symbol it provides is referenced by another object and that object is still resident. An executable object file that has no references to any of its symbols and was not explicitly loaded using the dlopen() call is orphaned and automatically removed from the address space.

$ sparc-rtems5-gcc -mcpu=cypress foo.o -lrtemsbsp -lrtemscpu -o foo.pre
$ rtems-syms -e -C sparc-rtems5-gcc -c "-mcpu=cypress" -o foo-sym.o foo.pre
$ sparc-rtems5-gcc -mcpu=cypress foo.o foo-sym.o -lrtemsbsp -lrtemscpu -o foo.exe

$ sparc-rtems5-gcc -mcpu=cypress foo.o -lrtemsbsp -lrtemscpu -o foo.exe
$ rtems-syms -C sparc-rtems5-gcc -c "-mcpu=cypress" -o foo-sym.o foo.exe

#include <stdbool.h>
#include <stdio.h>
#include <dlfcn.h>

bool load (void)
{
 void* handle = dlopen ("/foo-sym.o", RTLD_NOW | RTLD_GLOBAL);
 if (handle == NULL)
 {
   printf ("failed to load the symbol table: %s\n", dlerror ());
   return false;
 }
 return true;
}

8.7.4. Unresolved Symbols¶

The RTEMS link editor does not return an error when an executable object file is loaded with unresolved symbols. This allows dependent object files to be loaded. For example an executable object file foo.o contains the function foo() and that function calls bar() and an executable object file bar.o contains a function bar() that calls the function foo(). Either of these executable object files can be loaded first as long both are loaded before any symbols are accessed.

The link editor defers the resolution of unresolved symbols until the symbol is available in the global symbol table. Executing code or accessing data in a loaded executable object file with unresolved external symbols results in unpredictable behavior.

All unresolved symbols are checked after an executable object file has been loaded. If a symbol is found and resolved any relocations that reference the symbol are fixed. If valid library files have been configured the symbol table’s of each library are searched and if the symbol is found the dependent executable object file is loaded. This process repeats until no more symbols can be resolved.

The dlinfo() call can be used to see if a loaded executable object file has any unresolved symbols:

#include <stdbool.h>
#include <stdio.h>
#include <dlfcn.h>

bool has_unresolved(void* handle)
{
  int unresolved;
  if (dlinfo (handle, RTLD_DI_UNRESOLVED, &unresolved) < 0)
  {
    printf ("dlinfo failed: %s\n", dlerror ());
    return false;
  }
  return unresolved != 0;
}

The handle RTLD_SELF checks for any unresolved symbols in all resident object files:

if (has_unresolved(RTLD_SELF))
  printf("system has unsolved symbols\n");

8.7.5. Libraries¶

The RTEMS link editor supports loading executable object files from libraries. Executable object files can be explicitly loaded from a library using a specific path to dlopen() and treated the same as loading a stand alone executable object file. Libraries can be searched and an executable object file containing the search symbol can be loaded automatically as a dependent executable object file. A dependent executable object file loaded from a library with no symbol references to it’s symbols is orphaned and automatically unloaded and removed from the address space.

Loading Executable Object Files

A library is an archive format file created using the RTEMS architecture prefixed ar command. The RTEMS tool suite provides the ar program and system libraries such as libc.a and libm.a for each architecture and ABI. Libraries used by the RTEMS link editor for searching must contain a symbol table created by the ranlib program from the RTEMS tool suite.

Searching a library’s symbol table and loading an executable object file containing the symbol is called dependent loading. Dependent loading provides a simple way to manage the dependencies when loading an executable object file. If code in an executable object file references functions or data objects that are part of a library and the symbols are not part of the base image those symbols will not resolve unless the library is on the target and available for searching and loading. Dependent loading from libraries on the target provides a simple and understandable way to manage the dependency issue between the base image, loaded code and the system libraries.

The RTEMS link editor checks for the configuration file /etc/libdl.conf on each call to dlopen(). If the file has changed since the last check it is loaded again and the contents processed. The file format is:

1. Comments start with the # character.
2. A line is a wildcard path of libraries to search for. The wildcard search uses the fnmatch() call. The fnmatch() function matches patterns according to the rules used by a shell.

Files that match the search pattern are verified as a library and if a symbol table is found it is loaded and the symbols it contains made search-able.

A call to dlopen() checks the global symbols table and any references to relocation symbols not found are unresolved and added to the unresolved symbol table. Once the executable object file is loaded the link editor attempts to resolve any unresolved symbols. The unresolved symbol resolver checks each unresolved symbol against the global symbol table and if not found the available library symbol tables are searched. If a symbol is found in a library the dependent executable object file is loaded. The process repeats until all unresolved symbols have been resolved and the remaining unresolved symbols are not in the global symbol table or any libraries. The loading of a library executable object file will resolve at least one symbol and it may add more unresolved symbols requiring further searching of the libraries.

A library of executable object files built by the RTEMS Tool suite can contain debug information and this should be stripped before loading on to the target. The tool suite’s command strip can strip all the object files in a library with a single command.

$ sparc-rtems5-strip libc.a

8.7.6. Large Memory¶

The RTEMS link editor supports large memory relocations. Some architectures have instructions where the relative branch or jump offset from the instruction to the target address is limited. These instructions provide improved performance because less code generated compared to larger instructions which contain full address space references. The compact code helps lower cache pressure as well and providing improved performance for localalized functions and loops. The compiler defaults to generating the smaller instruction and as the final address map not known when generating the code, linkers need to provide glue code to extend the small address range to the enitre address space. This is called a trampoline. A trampoline is transparent to the execution of the code.

The link editor parses an executable object file’s relocation records to determine the number of trampolines needed. Added to this value are all unresolved symbols present in an executable object file after it is loaded. There is a slot allocated even if the symbol ends up being within range as there is no way to determine a symbol’s address until it is loaded and the range calculated.

The trampoline table is allocated a separate block of memory to the executable object file’s text, data and constants memory. The trampoline parsing requires the executable object file’s instructions (text) be in memory as the instructions are inspected by the architecture specific relocation support to determine an instruction’s range. As a result the allocation for the trampoline table has to occur after the text memory has been allocated. Most instructions have relative offsets and the trampoline table is allocated at one end limiting the size of an object to half the maximum range.

Trampolines support is available for the ARM and PowerPC architectures. The SPARC and Intel x86 architectures do not need trampolines and MIPS needs support added.

8.7.7. Allocator¶

The RTEMS link editor supports custom allocators. A custom allocator lets you manage the memory used by the RTEMS link editor as it runs. Allocators could provide:

1. Support for the various types of memory that can be allocated allowing specialised target support for specific use cases.
2. Locking of read-only memory. The link editor unlocks read-only memory when it needs to write to it.
3. Separation of memory holding code and data from the heap.

The allocator can be hooked using the rtems_rtl_alloc_hook call before any calls to dlopen() are made. The hook call returns the current allocate allowing the allocators to be chained.

The default allocator uses the heap.

The allocator tags specify the type of memory the allocator is handling. The tag used to allocate memory at an address must be used when making allocator calls. The rtems_rtl_alloc_tags are:

RTEMS_RTL_ALLOC_OBJECT

Allocate a generic object. The link editor uses this memory for data structures it uses to manage the linking process and resident executable object files.

RTEMS_RTL_ALLOC_SYMBOL

Allocate memory to hold symbol data.

RTEMS_RTL_ALLOC_EXTERNAL

Allocate memory for unresolved external symbols.

RTEMS_RTL_ALLOC_READ

Allocate memory for read-only data such as constants and exception tables.

RTEMS_RTL_ALLOC_READ_WRITE

Allocate memory for read-write data such as a initialised, uninitialized and common variables.

RTEMS_RTL_ALLOC_READ_EXEC

Allocate memory for code to be executed in. The address space is configure for read and execute.

The commands are used to control the action the allocator performs. The rtems_rtl_alloc_cmd are:

RTEMS_RTL_ALLOC_NEW

Allocate memory of the tag type. Returns NULL if the allocation fails.

RTEMS_RTL_ALLOC_DEL

Delete a previous allocation freeing the memory. The tag has to match address of the memory being deleted.

RTEMS_RTL_ALLOC_WR_ENABLE

Enable writes to a region of memory previously allocated. The tag has to match the address of the memory being write enabled. The link editor may call issue this command for memory that is already write enabled.

RTEMS_RTL_ALLOC_WR_DISABLE

Disable writes to a region of memory previously allocated. The tag has to match address of the memory being write disabled. The link editor may call issue this command for memory that is writable and not to be write disabled. The allocator need to manage this case.

The allocator handler is a single call to handle all allocator requests. The handler called on evey allocation action made by the link editor. The type of the function you need is:

typedef void (*rtems_rtl_allocator)(rtems_rtl_alloc_cmd cmd,
                                    rtems_rtl_alloc_tag tag,
                                    void**              address,
                                    size_t              size);

The arguments are:

cmd

The command to action. See rtems_rtl_alloc_cmd.

tag

The type of memory the command is for. The tag must match the address for commands other than RTEMS_RTL_ALLOC_OBJECT. See rtems_rtl_alloc_tags.

address

Pointer to the address. This is set of the RTEMS_RTL_ALLOC_OBJECT command and read for the other commands. The tag must match the address for commands that read the address from the pointer.

size

The size of the memory to allocate. This is only valid for the RTEMS_RTL_ALLOC_OBJECT command.

The call to hook the allocator is:

rtems_rtl_allocator rtems_rtl_alloc_hook (rtems_rtl_allocator handler);

The current allocator is returned. You can provide a full allocator or you can filter commands.

8.7.8. Languages¶

C is supported.

C++ is supported. Initializer functions are called when an object is loaded and finalizer functions are called before it is unloaded and removed. Static constructions are initializer functions and static destructors are finalizer functions.

C++ exceptions are handled across modules. The compiler generated exception tables present in an executable object file are registered with the architecture specific mechanism when loaded and deregistered when unloaded. An exception thrown in loaded code can be caught in the base image or another loaded module. If you are using C++ and exceptions it is recommended some exception code is added to the base image to place the architecture specific support in the base image.

8.7.9. Thread Local Storage¶

Thread local storage (TLS) is currenly not supported by the RTEMS link editor. The RTEMS executive needs to have a special allocator added to manage dynamically allocating TLS variables in a thread.

If you need TLS support in dynamically loaded code please consider the RTEMS support options.

8.7.10. Architectures¶

The following architectures are supported:

• ARM
• Blackfin
• H8300
• Intel x86 (i386)
• LM32
• M68K
• MIPS
• Moxie
• PowerPC
• SPARC
• V850

bsp_section_small_data_area_size = 65536;

8.8.1. Building the DTB¶

A single DTB file can be built using the dtc tool in libfdt using the following command:

dtc -@ -I dts -O dtb -o my-devicetree.dtb my-devicetree.dts

For building the DTB from the FreeBSD source, the make_dtb.sh script from freebsd/sys/tools/fdt must be used as most of the DTS files in FreeBSD have included .dtsi files from their source tree. An example is given below as a reference for how to build the device tree from the FreeBSD source.

NOTE: The following example uses FreeBSD master branch from github mirror as an example. It is advised to always use the source from the commit matching the freebsd-org HEAD in libBSD.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

  #We're using the script from freebsd/sys/tools/make_dtb.sh
  #Target device: Beaglebone Black.
  #Architecture: Arm.
  #DTS source name: am335x-boneblack.dts

  #The make_dtb.sh script uses environment variable MACHINE
  export MACHINE='arm'

  SCRIPT_DIR=$HOME/freebsd/sys/tools/fdt

  #The arguments to the script are
  # $1 -> Build Tree (This is the path to freebsd/sys/ directory)
  # $2 -> DTS source file
  # $3 -> output path of the DTB file

  ${SCRIPT_DIR}/make_dtb.sh ${SCRIPT_DIR}/../../ \
  ${SCRIPT_DIR}/../../gnu/dts/arm/am335x-boneblack.dts \
  $(pwd)

8.8.2. Using Device Tree Overlay¶

Device tree overlay is used either to add properties or devices to the existing device tree. Adding any property to DTS using an overlay will override the current values in the DTB. The Overlays enable us to modify the device tree using a small maintainable plugin without having to edit the whole Base Tree.

There are two ways of applying an overlay on top of the built DTB.

1. Use fdtoverlay from libfdt
2. Add the overlay in the root partition of the SD card and apply it using U-Boot

The fdtoverlay command can be used as follows:

fdtoverlay -i my-base-tree.dtb -o output-tree.dtb my-overlay.dtbo

To apply it from U-Boot during system initialization we have to add the device tree overlay file in the root directory of the SD card and use U-Boot commands to apply the overlay.

Below is given the series of U-Boot commands that can be used to apply the overlay, given that the overlay blob (.dtbo) file is already in the card.

fatload mmc 0:1 0x80800000 rtems-app.img
fatload mmc 0:1 0x88000000 my-base-tree.dtb
fdt addr 0x88000000
fatload mmc 0:1 0x88100000 my-overlay.dtbo
fdt resize 0x1000
fdt apply 0x88100000
bootm 0x80800000-0x88000000

9.2.1. Expected Test States¶

A test’s expected state is set in the RTEMS kernel’s testsuite. The default for a tested is to pass. If a test is known to fail it can have it’s state set to expected-fail. Setting tests that are known to fail to expected-fail lets everyone know a failure is not to be countered and consider a regression.

Expected test states are listed in test configuration files

9.2.2. Test Configuration¶

Tests can be configured for each BSP using test configuration files. These files have the file extension .tcfg. The testsuite supports global test configurations in the testsuite/testdata directory. Global test states are applied to all BSPs. BSPs can provide a test configuration that applies to just that BSP and these files can include subsets of test configurations.

The configuration supports:

1. Including test configuration files to allow sharing of common configurations.
2. Excluding tests from being built that do not build for a BSP.
3. Setting the test state if it is not passed.
4. Specifing a BSP specific build configuration for a test.

The test configuration file format is:

state: test

where the state is state of the test and test is a comma separated list of tests the state applies too. The configuration format is:

flags: test: configuration

where flags is the type of flags being set, the test is a comma separate list of regular expresions that match the test the configuration is applied too and the configuration is the string of flags.

The state is one of:

include

The test list is the name of a test configuration file to include

exclude

The tests listed are not build. This can happen if a BSP cannot support a test. For example it does not have enough memory.

expected-fail

The tests listed are set to expected fail. The test will fail on the BSP being built.

user-input

The tests listed require user input to run and are not supported by automatic testers.

indeterminate

The tests listed may pass or may not, the result is not reliable.

benchmark

The tests listed are benchmarks. Benchmarks are flagged and not left to run to completion because they may take too long.

Specialized filtering using regular expressions is supported using:

rexclude

The test matching the regular expression are excluded.

rinclude

The tests matching the regular expression are included.

By default all tests are included, specific excluded tests using the exclude state are excluded and cannot be included again. If a test matching a rexclude regular it is excluded unless it is included using a rinclude regular expression. For example to build only the hello sample application you can:

rexclude .*
rinclude hello

Test configuration flags can be applied to a range of tests using flags. Currently only cflags is support. Tests need to support the configuration for it to work. For example to configure a test:

cflags: tm.*: -DTEST_CONFIG=42
cflags: sp0[456]: -DA_SET_OF_TESTS=1

Flags setting are joined together and passed to the compiler’s command line. For example:

cflags: tm.*: -DTEST_CONFIG=42
cflags: tm03: -DTEST_TM03_CONFIG=1

would result in the command line to the test tm03 being:

-DTEST_CONFIG=42 -DTEST_TM03_CONFIG=1

Specific flags can be set for one test in a group. For example to set a configuration for all timer tests and a special configuraiton for one test:

cflags: (?!tm02)tm.*: -DTEST_CONFIG=one
cflags: tm02: -DTEST_CONFIG=two

9.4.1. Defaults¶

The RTEMS Tester and RTEMS Run are primed using defaults from the file rtems/testing/testing.mc. All default settings can be overridden in a BSP or User configuration file.

9.4.2. BSP and User Configuration¶

The BSP and User configuration files are INI format files. The BSP configuration file has to have an INI section that is the name of the BSP passed on the command line. The section has the following mandatory values:

bsp

The name of the BSP. The BSP name is used to create a macro map to hold the BSP’s configuration data. Typically this is the same as the BSP name used on the command line.

arch

The name of the BSP architecture. This is need for the GDB configuration scripts where the architecture specific GDB needs to run. It is mandatory so the arch/bsp standard RTEMS BSP string can be used.

tester

The tester or run configuration script. This is the name of the configuration script the RTEMS Tester or RTEMS Run executes as a back end. The tester value is typically of the form %{_rtscripts}/<script> where <script> is name of the back end script to be run.

Target commands support expansion of specific tags to provide a convenient way for users to customize a local test environment. The parameters expanded are:

@ARCH@

The BSP architecture.

@BSP@

The BSP’s name set by the bsp value.

@EXE@

The executable name as an absolute path

@FEXE@

The filtered executable if a target_exe_filter is provided else the executable’s file name.

The following are optional and depend on the back end being used and the local target hardware set up:

jobs

The jobs value sets the number of jobs that can be run at once. This setting only effects the RTEMS Tester. The tester can run up to the jobs value of tests concurrently. If the tester back end is a simulator running a job on each available core lowers the total test time. Overloading a machine with too many simulators running in parallel can slow down each simulation and test timeouts may be recorded.

bsp_tty_dev

The BSP’s tty device. This can be a real device on the host machine the executable is being run from or it can be a telnet server and port defined using the stand host format. See Consoles for details.

target_pretest_command

The pre-test command is a host shell command that is called before each test runs. It can be used to construct a suitable environment or image needed by a simulator or target. The RTEMS executate being run is provided as an argument and the bootloader specific format is the output.

target_posttest_command

The post-test command is a host shell command that is called after each test has finished. It can be used to destroy any environment or image created by the pre-test command.

target_exe_filter

The target executable filter transforms the executable name into a filtered executable name. This filter lets the tester or run command track the name of any generated file a pre-test command may generate. The syntax is a simplified sed regular expression. The first character is a delimiter and there must be 2 sections therefore 3 delimiter. The first section is a Python regular expression and the second section is plain text that replaces anywhere the regular expression matches. For example /\.exe/.exe.img/ will search for .exe in the executable name and replace it with .exe.img. Note, there is no need to escape the text in the second part, it is just plain test.

test_restarts

The number of restarts before the test is considered invalid. Currently not used.

target_reset_regex

The target reset regular expression. This is a Python regular expression used to filter the console input. If a match is made something has happened during the boot process that requires a reset. The target_reset_command is issued to perform the reset. Typically this field looks for boot loader error messages that indicate the boot process as failed.

target_start_regex

The target start regular expression. This is a Python regular expression to filter the console input to asynchronously detect if a target has reset. If a board crashes running a test or at any point reset this filter detects the restart and ends the test with a suitable result.

target_on_command

The target on command is a host shell command that is called before the first test. This command powers on a target. Targets should be left powered off when not running tests or the target may request TFTP downloads that are for another target interfering with those test results. We recommend you implement this command as a target off command, a pause, then a target on command.

target_off_command

The target off command is a host shell command that is called after the last test powering off the target.

target_reset_command

The target reset command is a host shell command that is called when the target needs to be reset. This command can power cycle the target or toggle a reset signal connected to the target. If you are power cycling a target make sure you have a suitable pause to let the target completely power down.

9.4.3. Configuration Scripts¶

Configuration scripts are provided for each supported RTEMS Tester and RTEMS Run back end and console management. The scripts are in the standard RTEMS Toolkit Configuration Script format. Please refer to the RTEMS Source Builder documentation for the basic scripting syntax and usage.

The RTEMS Tester and RTEMS Run specializes the standard configuration syntax providing a directive for the console and each supported back end. The supported directives are:

• %console
• %execute
• %gdb
• %tftp

%define bsp_tty_dev      /dev/ttyUSB2
%define bsp_tty_settings B115200,~BRKINT,IGNBRK,IGNCR,~ICANON,~ISIG,~IEXTEN,~ECHO,CLOCAL,~CRTSCTS,VMIN=1,VTIME=2

[bsp-special]
bsp              = example-bsp
bsp_tty_dev      = /dev/ttyUSB2
bsp_tty_settings = B115200,~BRKINT,IGNBRK,IGNCR,~ICANON,~ISIG,~IEXTEN,~ECHO,CLOCAL,~CRTSCTS,VMIN=1,VTIME=2

%execute %{run_cmd} %{run_opts} %{test_executable} %{test_executable_opts}

%gdb %{gdb_cmd} %{test_executable} %{gdb_script}

%tftp %{test_executable} %{tftp_port}

9.8.1. Target Hardware¶

The RTEMS Tester TFTP and U-Boot method of testing requires:

1. A target with network interface.
2. U-Boot, iPXE or similar boot loader with network driver support for your target hardware and support for the TFTP protocol.
3. Network power of IO switch.
4. Network DHCP server.
5. Console interface cable that matches your target’s console UART interface.
6. Telnet terminal server. See Consoles.

The network power or IO switch is a device that can control power or an IO pin over a network connection using a script-able protocol such as Telnet or curl. This device can be used with the target control commands.

loadaddr=0x02000000
uenvcmd=echo Booting RTEMS Zed from net; set autoload no; dhcp; set serverip 10.10.5.2; tftpboot zed/rtems.img; bootm; reset;

9.8.2. BSP Configuration¶

The BSP’s configuration file must contain the standard fields:

• bsp
• arch
• jobs - Must be set to 1.
• tester - Set to %{_rtscripts}/tftp.cfg

For example the Zedboard’s configuration is:

[xilinx_zynq_zedboard]
bsp    = xilinx_zynq_zedboard
arch   = arm
jobs   = 1
tester = %{_rtscripts}/tftp.cfg

The TFTP configuration supports the following field’s:

bsp_tty_dev

The target’s tty console. For telnet this is a host and port pair written in the standard networking format, for example serserver:12345.

test_restarts

The number of restarts before the test is considered invalid.

target_reset_regex

The target reset regular expression. This is a Python regular expression used to filter the console input. If a match is made something has happened during the boot process that requires a reset. The target_reset_command is issued to perform the reset. This field is typically looks for boot loader error messages that indicate the boot process as failed.

target_start_regex

The target start regular expression. This also a Python regular expression to filter the console input to detect if a target has reset. If a board crashes running a test or at any point in time and reset this filter detects this as happened and end the test with a suitable result.

target_on_command

The target on command is a host shell command that is called before the first test. This command powers on a target. Targets should be left powered off when not running tests or the target may request TFTP downloads that are for another target interfering with those test results. We recommend you implement this command as a target off command, a pause, then a target on command.

target_off_command

The target off command is a host shell command that is called after the last test powering off the target.

target_reset_command

The target reset command is a host shell command that is called when the target needs to be reset. This command can power cycle the target or toggle a reset signal connected to the target. If you are power cycling a target make sure you have a suitable pause to let the target completely power down.

target_pretest_command

The target pretest command is a host shell comment that is called before the test is run

The commands in the listed fields can include parameters that are substituted. The parameters are:

@ARCH@

The BSP architecture

@BSP@

The BSP’s name

@EXE@

The executable name.

@FEXE@

The

. The

@ARCH is the

substituted

Some of these field are normally provided by a user’s configuration. To do this use:

requires = bsp_tty_dev, target_on_command, target_off_command, target_reset_command

The requires value requires the user provide these settings in their configuration file.

The Zedboard’s configuration file is:

[xilinx_zynq_zedboard]
bsp                = xilinx_zynq_zedboard
arch               = arm
jobs               = 1
tester             = %{_rtscripts}/tftp.cfg
test_restarts      = 3
target_reset_regex = ^No ethernet found.*|^BOOTP broadcast 6.*|^.+complete\.+ TIMEOUT.*
target_start_regex = ^U-Boot SPL .*
requires           = target_on_command, target_off_command, target_reset_command, bsp_tty_dev

The target_start_regex searches for U-Boot’s first console message. This indicate the board can restarted.

The target_reset_regex checks if no ethernet interface is found. This can happen if U-Boot cannot detect the PHY device. It also checks if too many DHCP requests happen and finally a check is made for any timeouts reported by U-Boot.

An example of a user configuration for the Zedboard is:

[xilinx_zynq_zedboard]
bsp_tty_dev            = selserver:12345
target_pretest_command = zynq-mkimg @EXE@
target_exe_filter      = /\.exe/.exe.img/
target_on_command      = power-ctl toggle-on 1 4
target_off_command     = power-ctl off 1
target_reset_command   = power-ctl toggle-on 1 3

9.8.3. TFTP Sequences¶

Running a large number of tests on real hardware exposes a range of issues and RTEMS Tester is designed to be tolerant of failures in booting or loading that can happen, for example a hardware design. These sequence diagrams document some of the sequences that can occur when errors happen.

The simplest sequence is running a test. The target is powered on, the test is loaded and executed and a pass or fail is determined:

Test Pass and Fail Sequences

The target start filter triggers if a start condition is detected. This can happen if the board crashes or resets with no output. If this happens repeatedly the test result is invalid:

Target Start Filter Trigger

The reset filter triggers if an error condition is found such as the bootloader not being able to load the test executable. If the filter triggers the target_reset_command is run:

Target Reset Filter Trigger

If the RTEMS Tester does not detect a test has started it can restart the test by resetting the target. The reset command can toggle an IO pin connected to reset, request a JTAG pod issue a reset or turn the power off and on:

Target Timeout

10.1.1. RTEMS Trace Using Trace Buffering¶

This scheme of tracing goes through the flow of events described in a subsequent flowchart:

Step 1: The user creates an application and user configuration file. The configuration file specifies the use of the trace buffer generator and other standard initializations. The user then configures their BSP and invokes the trace linker using a command to link the application executable. The trace linker uses the application files in compiled format (ELF) and the libraries used to build the application for performing this link.

Step 2: The RTEMS Trace Linker reads the user’s configuration file and that results in it reading the standard Trace Buffering Configuration files installed with the RTEMS Trace Linker. The trace linker uses the target compiler and linker to create the trace enabled application executable. It wraps the functions defined in the user’s configuration with code that captures trace records into the statically allocated buffer. The trace wrapper code is compiled with the target compiler and the resulting ELF object file is added to the standard link command line used to link the application and the application is re-linked using the wrapping option of the GNU linker.

Step 3: The trace linker creates an executable which is capable of running on the target hardware or simulator.

Step 4: RTEMS shell provides the “rtrace” command to display and save trace buffers.

10.1.2. RTEMS Trace Using Printk¶

This scheme of tracing goes through the flow of events described in a subsequent flowchart:

Step 1: The user creates an RTEMS application in the normal manner as well as a Trace Linker configuration file. The configuration file specifies using the Printk trace mode and the functions to trace. The user invokes the Trace Linker with the configuration and the normal link command line used to the link the application executable. The application ELF object files and libraries, including the RTEMS libraries are standard and do not need to be built specially.

Step 2: The RTEMS Trace Linker reads the user’s configuration file and that results in it reading the standard Printk Trace Configuration files installed with the RTEMS Trace Linker. The trace linker uses the target compiler and linker to create the trace enabled application executable. It wraps the functions defined in the user’s configuration with code that prints the entry with arguments and exit and return value if any. The trace wrapper code is compiled with the target compiler and the resulting ELF object file is added to the standard link command line used to link the application and the application is relinked using the wrapping option of the GNU linker.

Step 3: The trace linker creates and RTEMS ELF executable that can be run on the target hardware or simulator.

Step 4: The application is run in the hardware directly or using a debugger. The printk() output appears on the target console and the user can save that to a file.

The Tracing Examples section describes generation of traces using Trace Buffering technique for the fileio testsuite available with RTEMS installation.

10.2.1. Features¶

Tracing using trace buffering consists of the following sets of features:

• Individual entry and exit records.
• Task details such as CPU, current priority, real priority, task state and interrupt state.
• Nano-second timestamp.
• Interrupt safe buffer management.
• Function argument capture.
• Return value capture.
• Shell command support to report to the console, save a buffer, assess status of tracing, or view buffers between specified index ranges.

10.2.2. Prerequisites¶

1. Setup RTEMS for the sparc/erc32 architecture-bsp pair to run the following example.
2. Download the fileio configuration file and store it on the top of the installed BSP’s directory.
3. Change the value of the keys: rtems-path and prefix according to your rtems installation. The rtems-path is the path to the bsp installation and prefix is the path to the tools used to build rtems. Also set the value of the rtems-bsp key to sparc/erc32.

10.2.3. Demonstration¶

Inside the RTEMS build directory (the directory where the fileio configuration has been stored) run the following commands to generate traces:

BSP is configured with the following command -

../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \
--enable-networking --enable-tests --enable-rtemsbsp=erc32 --enable-cxx

The next two commands are used to link the fileio executable.The -B option signifies the use of the complete path to the required directory or file. Write the full path instead of the path file: sparc-rtems5/erc32/lib/ in the following commands according to your installation. Also confirm the path of the fileio’s executable and object files in the last line of the command according to your installation.

sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \
-specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \
-fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration \
-Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress \
-o sparc-rtems5/c/erc32/testsuites/samples/fileio.exe sparc-rtems5/c/erc32/\
testsuites/samples/fileio/fileio-init.o

This is the trace linker command to generate and compile the wrapper c file for the application. The link command follows the escape sequence “–”. “-C” option denotes the name of the user configuration file and “-W” specifies the name of the wrapper c file.

rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \
-specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \
-fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration \
-Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress \
-o sparc-rtems5/c/erc32/testsuites/samples/fileio.exe sparc-rtems5/c/erc32/\
testsuites/samples/fileio/fileio-init.o

The following command is used to run the application. Hit enter key quickly and type “s” and “root” and “pwd” to run the rtems shell. Use the rtrace status, rtrace trace and rtrace save commands to know the status of the tracing, display the contents of the trace buffer and save the buffer to disk in the form of binary files. Use rtrace -l to list the availalble options for commands with rtrace.

sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/fileio.exe

The output from the above commands will be as follows:

*** BEGIN OF TEST FILE I/O ***
*** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
*** TEST STATE: USER_INPUT
*** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API
*** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0)
Press any key to start file I/O sample (20s remaining)
Press any key to start file I/O sample (19s remaining)
Press any key to start file I/O sample (18s remaining)
Press any key to start file I/O sample (17s remaining)
Press any key to start file I/O sample (16s remaining)
Press any key to start file I/O sample (15s remaining)
Press any key to start file I/O sample (14s remaining)
 =========================
 RTEMS FILE I/O Test Menu
 =========================
   p -> part_table_initialize
   f -> mount all disks in fs_table
   l -> list  file
   r -> read  file
   w -> write file
   s -> start shell
   Enter your selection ==>s
Creating /etc/passwd and group with four useable accounts:
  root/pwd
  test/pwd
  rtems/NO PASSWORD
  chroot/NO PASSWORD
Only the root user has access to all available commands.
 =========================
   starting shell
 =========================

Welcome to rtems-5.0.0 (SPARC/w/FPU/erc32)
COPYRIGHT (c) 1989-2008.
On-Line Applications Research Corporation (OAR).

Login into RTEMS
/dev/foobar login: root
Password:

RTEMS Shell on /dev/foobar. Use 'help' to list commands.
SHLL [/] # rtrace status
RTEMS Trace Bufferring: status
   Running:  yes
 Triggered:  yes
     Level:   0%
    Traces:   25
SHLL [/] # rtrace stop
RTEMS Trace Bufferring: stop
SHLL [/] # rtrace trace
RTEMS Trace Bufferring: trace
 Trace buffer: 0x20921d8
 Words traced: 1487
       Traces: 25
  0:00:40.983197010  2081910  0a010002 [  2/  2] > malloc((size_t) 00000130)
  0:00:40.983333119   136109  0a010002 [  2/  2] < malloc => (void*) 0x219bb88
  0:00:40.983471669   138550  0a010002 [  2/  2] > malloc((size_t) 00000006)
  0:00:40.983606557   134888  0a010002 [  2/  2] < malloc => (void*) 0x219bcc0
  0:00:40.983684682    78125  0a010002 [  2/  2] > malloc((size_t) 00000007)
  0:00:40.983819569   134887  0a010002 [  2/  2] < malloc => (void*) 0x219bcd0
  0:00:40.983909901    90332  0a010002 [  2/  2] > malloc((size_t) 000003fc)
  0:00:40.984046620   136719  0a010002 [  2/  2] < malloc => (void*) 0x219bce0
  0:00:40.986624137  2577517  0a010003 [200/200] > malloc((size_t) 00000080)
  0:00:40.986767569   143432  0a010003 [200/200] < malloc => (void*) 0x219bce0
  0:00:40.987531119   763550  0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 0000005d)
  0:00:40.987603751    72632  0a010003 [200/200] > malloc((size_t) 0000005d)
  0:00:40.987744743   140992  0a010003 [200/200] < malloc => (void*) 0x219bce0
  0:00:40.987824699    79956  0a010003 [200/200] < calloc => (void*) 0x219bce0
  0:00:40.988302604   477905  0a010003 [200/200] > malloc((size_t) 00000080)
  0:00:40.988446647   144043  0a010003 [200/200] < malloc => (void*) 0x219bd48
  0:00:40.988667595   220948  0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)
  0:00:40.988740837    73242  0a010003 [200/200] > malloc((size_t) 00000080)
  0:00:40.988884880   144043  0a010003 [200/200] < malloc => (void*) 0x219bdd0
  0:00:40.988964836    79956  0a010003 [200/200] < calloc => (void*) 0x219bdd0
  0:00:40.989042961    78125  0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)
  0:00:40.989110100    67139  0a010003 [200/200] > malloc((size_t) 00000080)
  0:00:40.989254143   144043  0a010003 [200/200] < malloc => (void*) 0x219be58
  0:00:40.989334099    79956  0a010003 [200/200] < calloc => (void*) 0x219be58
  0:00:40.990118401   784302  0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000061)
  0:00:40.990176995    58594  0a010003 [200/200] > malloc((size_t) 00000061)
  0:00:40.990309441   132446  0a010003 [200/200] < malloc => (void*) 0x219bd48
  0:00:40.990384515    75074  0a010003 [200/200] < calloc => (void*) 0x219bd48
  0:00:40.990870355   485840  0a010003 [200/200] > malloc((size_t) 00000080)
  0:00:40.991011346   140991  0a010003 [200/200] < malloc => (void*) 0x219bee0
  0:00:40.991227411   216065  0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)
  0:00:40.991296380    68969  0a010003 [200/200] > malloc((size_t) 00000080)
  0:00:40.991438593   142213  0a010003 [200/200] < malloc => (void*) 0x219bf68
  0:00:40.991514276    75683  0a010003 [200/200] < calloc => (void*) 0x219bf68
  0:00:40.991589349    75073  0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)
  0:00:40.991653437    64088  0a010003 [200/200] > malloc((size_t) 00000080)
  0:00:40.991794428   140991  0a010003 [200/200] < malloc => (void*) 0x219bff0
  0:00:40.991871332    76904  0a010003 [200/200] < calloc => (void*) 0x219bff0
  0:00:40.992283320   411988  0a010003 [200/200] > malloc((size_t) 00000008)
SHLL [/] # rtrace save fileio-trace.bin
RTEMS Trace Bufferring: trace
   Trace File: fileio-trace.bin
   Trace buffer: 0x20921d8
   Words traced: 1487
       Traces: 25
SHLL [/] #

10.3.1. Capture Engine Commands¶

1. copen <buffer-size>: Used to initialize the Capture Engine with the trace buffer size in bytes. By default the Capture Engine is not initialized and not running.
2. cwceil <priority-value>: Capture Engine filter used to put an upper limit on the event priority to be captured.
3. cwfloor <priority-value>: Capture Engine filter used to put a lower limit on the event priority to be captured.
4. cwglob <on/off>: Enable or disable the global watch.
5. cenable: Enables the Capture Engine. Capture Engine is by default disabled after being opened.
6. cdisable: Disables the Capture Engine.
7. ctlist: Lists the watch and trigger configurations.
8. ctrace: Dumps the recorded traces. By default this command displays 24 trace records. Repeated use of this command will display all the recorded traces.
9. cwadd <task-name>: Add watch on a particular task.
10. cwtctl <task-name> <on/off>: Enable or disable watch on a particular task.
11. ctset: Used to set a trigger. The general form of the command is:

ctset [-?] type [to name/id] [from] [from name/id]

type in the above command refers to the type of trigger needed. The types of triggers that currently exist are:

• switch : a context switch from one task to another task
• create : the executing task creates a task
• start : the executing task starts a task
• restart : the executing task restarts a task
• delete : the executing task deletes a task
• begin : a task is beginning
• exitted : a task is exitting

10.3.2. Example¶

The following is a sample run of the capture testsuite. The test1 command on the Capture Engine Command Line Interface (CLI) makes the RMON task invoke a call to the capture_test_1() command. This function (in the test1.c source code) creates and starts three tasks : CT1a, CT1b and CT1c. These tasks are passed the object id of a semaphore as a task argument. This run through traces the context switches between these tasks. cwceil and cwfloor are set to a narrow range of task priorities to avoid creating noise from a large number of context switches between tasks we are not interested in.

*** BEGIN OF TEST CAPTURE ENGINE ***
*** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
*** TEST STATE: USER_INPUT
*** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API
*** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0)
Press any key to start capture engine (20s remaining)
Press any key to start capture engine (19s remaining)
Press any key to start capture engine (18s remaining)
Press any key to start capture engine (17s remaining)

Monitor ready, press enter to login.

1-rtems $ copen 50000
capture engine opened.
1-rtems $ cwceil 100
watch ceiling is 100.
1-rtems $ cwfloor 102
watch floor is 102.
1-rtems $ cwglob on
global watch enabled.
1-rtems $ ctset RMON
trigger set.
1-rtems $ cenable
capture engine enabled.
1-rtems $ test1
1-rtems $ cdisable
capture engine disabled.
1-rtems $ ctrace
0 0:18:17.462314124           0a010003 CT1a 102 102 102   4096  TASK_RECORD
0 0:18:17.462398963         0 0a010003 CT1a 102 102             CREATED
0 0:18:17.462647987    249024 0a010003 CT1a 102 102             STARTED
0 0:18:17.462904334    256347 0a010003 CT1a 102 102             SWITCHED_IN
0 0:18:17.463069129    164795 0a010003 CT1a 102 102             BEGIN
0 0:18:17.463335853    266724 0a010003 CT1a 102 102             SWITCHED_OUT
0 0:18:18.461348547           0a010004 CT1b 101 101 101   4096  TASK_RECORD
0 0:18:18.461433997 998098144 0a010004 CT1b 101 101             CREATED
0 0:18:18.461683631    249634 0a010004 CT1b 101 101             STARTED
0 0:18:18.461934485    250854 0a010004 CT1b 101 101             SWITCHED_IN
0 0:18:18.462099891    165406 0a010004 CT1b 101 101             BEGIN
0 0:18:19.460935339 998835448 0a010004 CT1b 101 101             SWITCHED_OUT
0 0:18:19.461431555           0a010005 CT1c 100 100 100   4096  TASK_RECORD
0 0:18:19.461516394    581055 0a010005 CT1c 100 100             CREATED
0 0:18:19.461765418    249024 0a010005 CT1c 100 100             STARTED
0 0:18:19.462019324    253906 0a010005 CT1c 100 100             SWITCHED_IN
0 0:18:19.462184119    164795 0a010005 CT1c 100 100             BEGIN
0 0:18:19.462475257    291138 0a010005 CT1c 100 100             SWITCHED_OUT
0 0:18:19.462551551     76294 0a010004 CT1b 101 101             SWITCHED_IN
0 0:18:19.960935645 498384094 0a010004 CT1b 101 101             SWITCHED_OUT
0 0:18:19.961012549     76904 0a010003 CT1a 102 100             SWITCHED_IN
0 0:18:19.961341528    328979 0a010003 CT1a 102 102             SWITCHED_OUT
1-rtems $ ctrace
0 0:18:19.961418433         0 0a010005 CT1c 100 100             SWITCHED_IN
0 0:18:19.961672339    253906 0a010005 CT1c 100 100             SWITCHED_OUT
0 0:18:19.961749854     77515 0a010004 CT1b 101 101             SWITCHED_IN
0 0:18:20.460967077 499217223 0a010004 CT1b 101 101             SWITCHED_OUT
0 0:18:20.461219763    252686 0a010005 CT1c 100 100             SWITCHED_IN
0 0:18:20.461424231    204468 0a010005 CT1c 100 100             TERMINATED
0 0:18:20.461747107    322876 0a010005 CT1c 100 100             SWITCHED_OUT
0 0:18:20.461824011     76904 0a010004 CT1b 101 101             SWITCHED_IN
0 0:18:20.462015052    191041 0a010004 CT1b 101 101             TERMINATED
0 0:18:20.462336707    321655 0a010004 CT1b 101 101             SWITCHED_OUT
0 0:18:20.462414222     77515 0a010003 CT1a 102 102             SWITCHED_IN
0 0:18:20.462608924    194702 0a010003 CT1a 102 102             TERMINATED
0 0:18:20.462933021    324097 0a010003 CT1a 102 102             SWITCHED_OUT
1-rtems $ ctrace
1-rtems $

10.4.1. Command Line¶

A typical command to invoke the trace linker consists of two parts separated by --. The first part controls the trace linker and provides the various options it needs and the second part is a standard linker command line you would use to link an RTEMS application. The current command line for trace linker consists of:

$ rtems-tld -h
rtems-trace-ld [options] objects
Options and arguments:
 -h          : help (also --help)
 -V          : print linker version number and exit (also --version)
 -v          : verbose (trace import parts), can supply multiple times
               to increase verbosity (also --verbose)
 -w          : generate warnings (also --warn)
 -k          : keep temporary files (also --keep)
 -c compiler : target compiler is not standard (also --compiler)
 -l linker   : target linker is not standard (also --linker)
 -E prefix   : the RTEMS tool prefix (also --exec-prefix)
 -f cflags   : C compiler flags (also --cflags)
 -r path     : RTEMS path (also --rtems)
 -B bsp      : RTEMS arch/bsp (also --rtems-bsp)
 -W wrapper  : wrapper file name without ext (also --wrapper)
 -C ini      : user configuration INI file (also --config)
 -P path     : user configuration INI file search path (also --path)

The trace linker generates code that needs to be compiled and linked to the application executable so it needs to know the target compiler and CFLAGS. There are a couple of ways to do this. The simplest is to provide the path to RTEMS using the -r option and the architecture and BSP name in the standard RTEMS format of arch/bsp. The trace linker will extract the compiler and flags used to build RTEMS and will use them. If you require specific options you can use the -f, -c, -l, and -E options to provide them. If the functions you are tracing use types from your code then add the include path to the CFLAGS.

The trace linker requires you to provide a user configuration file using the -C or --config option. This is an INI format file detailed in the Configuration section. You can also provide an INI file search path using the -P option.

If you are working with new configuration files and you want to view the files the trace linker generates, add the -k option to keep the temporary files, and -W to specify an explicit wrapper C file name. If you set the dump-on-error option in the configuration options section you will get a dump of the configuration on an error.

10.4.2. Configuration (INI) files¶

The Trace Linker is controlled using configuration files. Configuration files are categorized into 3 types:

• User Configuration: These are specific to the user application to be traced. This file initializes the values of the trace generator, triggers, enables, and traces.
• Tracer Configuration: These are like a library of common or base trace functions that can be referenced by an application. These files tend to hold the details needed to wrap a specific set of functions. Examples provided with the RTEMS Linker are the RTEMS API and Libc.
• Generator Configuration: This is used to encapsulate a specific method of tracing. RTEMS currently provides generators for trace buffering, printk, and printf.

The configuration files are in the INI file format which is composed of sections. Each section has a section name and set of keys which consist of names and values. A typical key is of the form name=value. Keys can be used to include other INI files using the include key name. This is shown in the following example where the values indicate rtems and rtld-base configuration files:

include = rtems.ini, rtld-base.ini

The trace linker also uses values in keys to specify other sections. In this example the functions name lists test-trace-funcs and that section contains a headers key that further references a section called test-headers:

functions = test-trace-funcs, rtems-api

[test-trace-funcs]
; Parsed via the 'function-set', not parse as a 'trace'.
headers = test-headers

[test-headers]
header = '#include "test-trace-1.h"'

The format of a configuration file is explained next. Snippets of the file: test-trace.ini have been used for explicit understanding. This file can be found in the rtems-tools directory of the rtems installation.

;
; RTEMS Trace Linker Test Configuration.
;
; We must provide a top level trace section.
;
[tracer]
;
; Name of the trace.
;
name = RTEMS Trace Linker Test
;
; The BSP.
;
bsp = sparc/sis
;
; Functions to trace.
;
traces = test-trace, test-trace-funcs, rtems-api-task
;
; Specify the options.
;
options = test-options
;
; Define the function sets. These are the function's that can be
; added to the trace lists.
;
functions = test-trace-funcs, rtems-api
;
; Include RTEMS Trace support.
;
include = rtems.ini, rtld-base.ini

;
; Options can be defined here or on the command line.
;
[test-options]
prefix = /development/rtems/5
verbose = true

; User application trace example.
;
[test-trace]
generator = printf-generator
; Just here for testing.
trace = test_trace_3

[test-trace-funcs]
; Parsed via the 'function-set', not parse as a 'trace'.
headers = test-headers
header = '#include "test-trace-2.h"'
defines = test-defines
define = "#define TEST_TRACE_2 2"
signatures = test-signatures
; Parsed via the 'trace', not parsed as a function-set
trace = test_trace_1, test_trace_2

[test-headers]
header = '#include "test-trace-1.h"'

[test-defines]
define = "#define TEST_TRACE_1 1"

[test-signatures]
test_trace_1 = void, int
test_trace_2 = test_type_2, test_type_1
test_trace_3 = float, float*

;
; A printf generator prints to stdout the trace functions.
;
[printf-generator]
headers = printf-generator-headers
entry-trace = "rtld_pg_printf_entry(@FUNC_NAME@, (void*) &@FUNC_LABEL@);"
arg-trace = "rtld_pg_printf_arg(@ARG_NUM@, @ARG_TYPE@, @ARG_SIZE@, (void*) &@ARG_LABEL@);"
exit-trace = "rtld_pg_printf_exit(@FUNC_NAME@, (void*) &@FUNC_LABEL@);"
ret-trace = "rtld_pg_printf_ret(@RET_TYPE@, @RET_SIZE@, (void*) &@RET_LABEL@);"
code = <<<CODE
static inline void rtld_pg_printf_entry(const char* func_name,
                                        void*       func_addr)
{
  printf (">>> %s (0x%08x)\n", func_name, func_addr);
}
static inline void rtld_pg_printf_arg(int         arg_num,
                                      const char* arg_type,
                                      int         arg_size,
                                      void*       arg)
{
  const unsigned char* p = arg;
  int   i;
  printf (" %2d] %s(%d) = ", arg_num, arg_type, arg_size);
  for (i = 0; i < arg_size; ++i, ++p) printf ("%02x", (unsigned int) *p);
  printf ("\n");
}
static inline void rtld_pg_printf_exit(const char* func_name,
                                       void*       func_addr)
{
  printf ("<<< %s (0x%08x)\n", func_name, func_addr);
}
static inline void rtld_pg_printf_ret(const char* ret_type,
                                      int         ret_size,
                                      void*       ret)
{
  const unsigned char* p = ret;
  int   i;
  printf (" rt] %s(%d) = ", ret_type, ret_size);
  for (i = 0; i < ret_size; ++i, ++p) printf ("%02x", (unsigned int) *p);
  printf ("\n");
}
CODE

[printf-generator-headers]
header = "#include <stdio.h>"

10.4.3. Development¶

The Trace Linker is part of the RTEMS tools git repository available at : https://git.rtems.org/rtems-tools The RTEMS tools project utilizes the waf build system. Use the following commands in the topmost build directory to build the tools project:

First we configure using:

$./waf configure --prefix=$HOME/development/rtems/5

Then we build and install using:

$./waf build install

11.2.1. Symbol Table¶

The symbol table is an ELF object file in the target’s ELF format and is built using the target’s RTEMS C compiler. The rtems-syms command searches for the C compller under the prefix this command is installed under or the system path. If the target’s C compiler is not located in either of these paths use the option -c or --cc to specify the path to the compiler.

The rtems-syms command loads the base kernel image’s ELF file and reads the global or public symbols, creates a temporary C file and then compiles it using the target’s RTEMS C compiler. The command automatically detects the architecture from the base kernel image’s ELF file and uses it to create the C compiler’s name. The option -E or --exec-prefix can be used to override the executable prefix used.

It is important to supply suitable C compiler flags (cflags) that match the kernel image’s so the symbol table can be linked or loaded.

11.2.2. 2-Pass Linking¶

2-Pass linking is used to embed a symbol table in a base kernel image. The first link pass is a normal RTEMS kernel link process. The link output is passed to the rtems-syms command and the -e or --embed option is used. The symbol table object file created by rtems-syms is added to the linker command used in the first pass to create the second pass. The address map will change between the first pass and second pass without causing a problem, the symbol table embedded in the second link pass will adjust the symbol addresses to match.

11.2.3. Command¶

rtems-syms [options] kernel

-V, --version¶

Display the version information and then exit.

-v, --verbose¶

Increase the verbose level by 1. The option can be used more than once to get more detailed trace and debug information.

-w, --warn¶

Enable build warnings. This is useful when debugging symbol table generation.

-k, --keep¶

Do not delete temporary files on exit, keep them.

-e, --embed¶

Create a symbol table that can be embedded in the base kernel image using a 2-pass link process.

-S, --symc¶

Specify the symbol’s C source file. The defautl is to use a temporary file name.

-o, --output¶

Specify the ELF output file name.

-m, --map¶

Create a map file using the provided file name.

-C, --cc¶

Specify the C compile executable file name. The file can be absolute and no path is search or relative and the environment’s path is searched.

-E, --exec-prefix¶

Specify the RTEMS tool prefix. For example for RTEMS 5 and the SPARC architecture the prefix is sparc-rtems5.

-c, --cflags¶

Specify the C compiler flags used to build the symbol table with. These should be the same or compatible with the flags used to build the RTEMS kernel.

-?, -h¶

Reort the usage help.

11.2.4. Examples¶

Create a dynamlically loaded symbol table for the minimum.exe sample program for the i386/pc686 BSP:

$ rtems-syms -o ms.o i386-rtems5/c/pc686/testsuites/samples/minimum/minimum.exe
$ file ms.o
ms.o: ELF 32-bit LSB relocatable, Intel 80386, version 1 (SYSV), not stripped

Run the same command, this time create a map file:

$ rtems-syms -o ms.o -m ms.map i386-rtems5/c/pc686/testsuites/samples/minimum/minimum.exe
$ head -10 ms.map
RTEMS Kernel Symbols Map
 kernel: i386-rtems5/c/pc686/testsuites/samples/minimum/minimum.exe

Globals:
 No.  Index Scope      Type        SHNDX  Address    Size    Name
    0   931 STB_GLOBAL STT_OBJECT      11 0x0012df08       4 BSPBaseBaud   (minimum.exe)
    1  1124 STB_GLOBAL STT_OBJECT      11 0x0012d894       4 BSPPrintkPort   (minimum.exe)
    2   836 STB_GLOBAL STT_FUNC         1 0x00104b00     302 BSP_dispatch_isr   (minimum.exe)
    3  1156 STB_GLOBAL STT_FUNC         1 0x001082d0      92 BSP_install_rtems_shared_irq_handler   (minimum.exe)
    4   876 STB_GLOBAL STT_FUNC         1 0x00106500     138 BSP_outch   (minimum.exe)

Run the same command with a raise verbose level to observe the stages the command performs:

$ rtems-syms -vvv -o ms.o i386-rtems5/c/pc686/testsuites/samples/minimum/minimum.exe
RTEMS Kernel Symbols 5.a72a462adc18
kernel: i386-rtems5/c/pc686/testsuites/samples/minimum/minimum.exe
cache:load-sym: object files: 1
cache:load-sym: symbols: 1043
symbol C file: /tmp/rld--X7paaa.c
symbol O file: ms.o
execute: i386-rtems5-gcc -O2 -c -o ms.o /tmp/rld--X7paaa.c
execute: status: 0

11.3.1. System Initialisation¶

Linker based system initialisation automatically lets RTEMS only link into the executable the system initialisation code referenced by the user’s application or indirectly by RTEMS. The technique is a varation of the system initialisation process used in the FreeBSD kernel. It is also similar to the process used by the C++ language to run static constructors before entering main and destructors after exit is called.

Linker based system initialisation collects the address of referenced system initialisation functions in specially named sections. The system initialisation function’s address is placed in a variable and the section attribute of the variable is set to a special section name. The linker is instructed via a special linker command file to collect these variables together to create a table. The start-up code in RTRMS loops over the table of addresses and calling each address or system initialisation function. Special section names given to the variables sorts the table placing the functions in a specific order.

A user places a call to an API function in their application and the linker pulls the API code from the RTEMS kernel library adding it to the executing. The API code the linker loads references the variable containing the address of the that API’s system initialisation function. The linker loads the API system initialisation code into the executable to resolve the external refernece created by the variable. If the user does not reference the API the variables is loaded into the executable and no reference to the API system initialisation code is made so it is not linked into the executable.

The design automatically creates a unique system intialisation table for each executable and the code in RTEMS does not change, there is no special build system tricks, or stub libraries.

The RTEMS Execuable Information reports the tables created and you can use this information to debug any initialisation issues.

11.3.2. Command¶

The rtems-exeinfo tool reports RTEMS specific information about the executable. The init and fini tables print the symbol referenced for each table entry and if the symbol is from the C++ language it is demangled.

rtems-exeinfo

-V¶

Display the version information and then exit.

-v¶

Increase the verbose level by 1. The option can be used more than once to get more detailed trace and debug information.

-a¶

Report all types of output data.

-I¶

Report the init or initialisation table.

-F¶

Report the fini or finialisation table.

-S¶

Report the sections.

-?, -h¶

Reort the usage help.

11.3.3. Examples¶

Prints all reports for the hello.exe for the i386/pc686 BSP:

$ rtems-exeinfo -a i386-rtems5/c/pc686/testsuites/samples/hello/hello.exe
RTEMS Executable Info 5.6f5cfada964c
 rtems-exeinfo -a i386-rtems5/c/pc686/testsuites/samples/hello/hello.exe
exe: i386-rtems5/c/pc686/testsuites/samples/hello/hello.exe
Sections: 22
                 -------------- addr: 0x00000000 0x00000000 size:          0 align:   0 relocs:      0
  .bss           WA------------ addr: 0x00135760 0x0013b300 size:      23456 align:  32 relocs:      0
  .comment       ---MS--------- addr: 0x00000000 0x00000083 size:        131 align:   1 relocs:      0
  .ctors         WA------------ addr: 0x0013322c 0x00133234 size:          8 align:   4 relocs:      0
  .data          WA------------ addr: 0x00133240 0x0013574c size:       9484 align:  32 relocs:      0
  .debug_abbrev  -------------- addr: 0x00000000 0x0003c5ce size:     247246 align:   1 relocs:      0
  .debug_aranges -------------- addr: 0x00000000 0x00003a18 size:      14872 align:   8 relocs:      0
  .debug_info    -------------- addr: 0x00000000 0x0032496d size:    3295597 align:   1 relocs:      0
  .debug_line    -------------- addr: 0x00000000 0x0006606b size:     417899 align:   1 relocs:      0
  .debug_loc     -------------- addr: 0x00000000 0x0003b704 size:     243460 align:   1 relocs:      0
  .debug_ranges  -------------- addr: 0x00000000 0x00008128 size:      33064 align:   1 relocs:      0
  .debug_str     ---MS--------- addr: 0x00000000 0x0001a9d7 size:     109015 align:   1 relocs:      0
  .dtors         WA------------ addr: 0x00133234 0x0013323c size:          8 align:   4 relocs:      0
  .eh_frame      -A------------ addr: 0x0012b884 0x0013222c size:      27048 align:   4 relocs:      0
  .fini          -AE----------- addr: 0x00127fdd 0x00127fe5 size:          8 align:   1 relocs:      0
  .init          -AE----------- addr: 0x00127fd0 0x00127fdd size:         13 align:   1 relocs:      0
  .rodata        -A------------ addr: 0x00128000 0x0012b884 size:      14468 align:  32 relocs:      0
  .rtemsroset    WA------------ addr: 0x00127f94 0x00127fd0 size:         60 align:   4 relocs:      0
  .shstrtab      -------------- addr: 0x00000000 0x000000c6 size:        198 align:   1 relocs:      0
  .strtab        -------------- addr: 0x00000000 0x000068ca size:      26826 align:   1 relocs:      0
  .symtab        -------------- addr: 0x00000000 0x00006290 size:      25232 align:   4 relocs:      0
  .text          WAE----------- addr: 0x00100000 0x00127f91 size:     163729 align:  16 relocs:      0

Init sections: 3
 .ctors
  0xffffffff RamSize
  0x00000000 REG_EFLAGS
 .init
  0xfd81ebe8 no symbol
  0xff86e8ff no symbol
  0x00c2ffff no symbol
 .rtemsroset
  0x00100310 bsp_work_area_initialize
  0x00100440 bsp_start_default
  0x001160e0 _User_extensions_Handler_initialization
  0x0010fe60 rtems_initialize_data_structures
  0x0010fcf0 _RTEMS_tasks_Manager_initialization
  0x0010f310 _Semaphore_Manager_initialization
  0x0010ed90 _POSIX_Keys_Manager_initialization
  0x00113af0 _Thread_Create_idle
  0x0010c100 rtems_libio_init
  0x0010bec0 rtems_filesystem_initialize
  0x00100420 bsp_predriver_hook
  0x0010bfb0 _Console_simple_Initialize
  0x0010ff30 _IO_Initialize_all_drivers
  0x0010fc10 _RTEMS_tasks_Initialize_user_tasks_body
  0x0010ccb0 rtems_libio_post_driver

Fini sections: 2
 .dtors
  0xffffffff RamSize
  0x00000000 REG_EFLAGS
 .fini
  0xfd815ee8 no symbol
  0x0000c2ff no symbol

The Init section .rtemsroset shows the initialisation call order for the hello.exe sample application. The order is initialise the BSP work area, call the BSP start up, initialise the User extensions, initialise the RTEMS data structures, then call the various Classic API managers that have been linked into the application. Next any POSIX managers are initialisations, in this case the POSIX Keys manager which is used by the thread local storage (TLS) support. Finally the IO and file system is initialise followed by the drivers.

Print the Init section data for the cdtest.exe for the i386/pc686 BSP:

$ rtems-exeinfo -I i386-rtems5/c/pc686/testsuites/samples/cdtest/cdtest.exe
RTEMS Executable Info 5.6f5cfada964c
 rtems-exeinfo -I i386-rtems5/c/pc686/testsuites/samples/cdtest/cdtest.exe
exe: i386-rtems5/c/pc686/testsuites/samples/cdtest/cdtest.exe
Init sections: 3
 .ctors
  0xffffffff RamSize
  0x00100ea0 _GLOBAL__sub_I_rtems_test_name
  0x001015d0 __gnu_cxx::__freeres()
  0x00101df0 __cxxabiv1::__terminate(void (*)())
  0x00102ac0 _GLOBAL__sub_I___cxa_get_globals_fast
  0x00103260 std::nothrow
  0x00000000 REG_EFLAGS
 .init
  0xfcb3dbe8 no symbol
  0xff86e8ff no symbol
  0x00c2ffff no symbol
 .rtemsroset
  0x001112c0 bsp_work_area_initialize
  0x001113f0 bsp_start_default
  0x001276c0 _User_extensions_Handler_initialization
  0x00121260 rtems_initialize_data_structures
  0x001210f0 _RTEMS_tasks_Manager_initialization
  0x00120710 _Semaphore_Manager_initialization
  0x0011ff70 _POSIX_Keys_Manager_initialization
  0x001250d0 _Thread_Create_idle
  0x0011d220 rtems_libio_init
  0x0011cfe0 rtems_filesystem_initialize
  0x001113d0 bsp_predriver_hook
  0x0011d0d0 _Console_simple_Initialize
  0x00121310 _IO_Initialize_all_drivers
  0x00121010 _RTEMS_tasks_Initialize_user_tasks_body
  0x0011ddd0 rtems_libio_post_driver

The C++ constructor section .ctors shows you the C++ static objects the RTEMS kernel will construct before calling main.

11.4.1. Developer Workflows¶

There are a number of RTEMS developers each with a different view or expertise in RTEMS. Developers can work in the generic areas such as scheduling, file systems or the shell, or users can become developers adding a new BSP, or even a new port to a new architecture. A common approach for all these developers is to select a BSP and to work with that BSP. Developers working in a generic areas of RTEMS tend to select a BSP that has good simulator support with good debugging such as QEMU, while developers of a new BSP or a new port tend to work on target hardware. This type of development does not check the other architectures, BSP, and build options and a change may change the number of warnings or introduce build errors. It is important for the RTEMS project to have developers fix these issues before pushing the changes to the master repository to avoid breaking the code for other developers. It is best for a developer to resolve as many issues as they work on changes because comming back to a problem often proves difficult.

The RTEMS BSP Builder forms part of a developers workflow where patches are tested before being pushed to the repository.

11.4.2. Build Characteristics¶

Build characteristic are the various parts of a build that can varied changing what is built. RTEMS can vary builds based on:

1. Architecture
2. Board Support Package (BSP)
3. Build options
4. BSP Options

The BSP Builder provides a template of builds to try and reduce the possble combinations to something manageable. It is not realistic to build all possible combinations on a single machine in reasonible time.

The RTEMS BSP Builder specifies it builds in terms of:

1. Profiles
2. Architectures
3. BSPs
4. Builds

The RTEMS BSP Builder builds are created by user options that vary these parameters.

11.4.3. Build Configurations¶

Build configurations are configure options. These are mapped to the various builds. The configurations are:

base	--target=@ARCH@-rtems@RTEMS_VERSION@ --enable-rtemsbsp=@BSP@ --prefix=@PREFIX@
tests	--enable-tests
debug	--enable-debug
no-debug	--disable-debug
profiling	--enable-profiling
no-profiling	--disable-profiling
smp	--enable-smp
no-smp	--disable-smp
posix	--enable-posix
no-posix	--disable-posix
network	--enable-networking
no-network	--disable-networking

11.4.4. Performance¶

The RTEMS BSP Builder is designed to extract the maximum performance from your hardware when building RTEMS. The RTEMS build system is based on autoconf, automake and GNU make. Building consists of two phases:

1. Configuring
2. Building

The Configuring phase and the start of the Build phase runs autoconf’s configure scripts. These execute as a single linear process and are not run in parallel even if you specify more than one job to make. The configure part of a build is approximately 30% of the total time and higher if building the tests. Performing a single build at a time will not fully utilized a multi-core machine because of the large amount of time the system is idle.

The RTEMS BSP Builder can run more than one build in parallel. A build can also request make run its build with more than one job. The --jobs option lets a user specify the number of build jobs to run at once and the number of make jobs each build runs with. Together these options can fully load a system and can overload a machine.

Tuning the best ratio of buld jobs to make jobs requires running some builds and observing the system’s performance. If the build job count is too low the system will show idle periods and if you have too many build jobs with too many make jobs the system will have too many processing running and the operating system’s overheads in administting too processes at once lowers the overall performance.

A fast eight core machine where the operating system shows sixteen cores can support a build option of --jobs=5/10. The machine will be fully loaded the average build time is around 18 seconds.

The type of build selected effects the optimum jobs option. For example building the tests changes the percentage of time spent configuring copmared to bulding so the make jobs parameter becomes a dominant factor. Lowering the make jobs value avoids having too many active processes running at once.

11.4.5. Command¶

rtems-bsp-builder [options]

-?¶

Display a compact help.

-h, --help¶

Display the full help.

--prefix¶

Prefix to pass to configure when building a BSP.

--rtems-tools¶

The path the RTEMS tools such as the C compiler. This option avoid polluting your path. This path is to the tool’s prefix used to build and install the tools and not exact path to an executable.

--rtems¶

The path the RTEMS source tree to build.

--build-path¶

The path to build the BSP and place the build output. This can be any path and away from your current directory or the RTEMS source code. The storage does not need to be fast like an SSD.

--log¶

The log file.

--config-report¶

Print a configuration report and exit.

--warnings-report¶

Create a warnings report once all builds have finished.

--stop-on-error¶

Stop the build on an error. The default is to build all the builds for a profile.

--no-clean¶

Do not remove the build once finished. This option lets you inspect the built output. The amount of output can be large and disks can fill with this option.

--profiles¶

Build the comma separated list of profiles. The default is tier-1.

--arch¶

A comma separated list of architecures to build using the selected build.

--bsp¶

A comma separated list of BSPs to build where a BSP is of the format arch/bsp using the selected build.

--build¶

The build to be used. The default is all. See --config-report for a list of vlaid builds.

--jobs¶

The jobs options where the format is build-jobs/make-jobs. The default is 1/num-cores where num-cores is the operating system reported number of cores.

--dry-run¶

Do not do the actual builds just show what would be built.

$ /opt/rtems/5/bin/rtems-bsp-builder --build-path=/build/rtems \
          --rtems-tools=/opt/work/rtems/5 \
          --rtems=/opt/work/chris/rtems/kernel/rtems.git \
          --profiles=tier-1 \
          --jobs=5/10
RTEMS Tools Project - RTEMS Kernel BSP Builder, 5.not_released
Profile(s): tier-1
Cleaning: bsp-builds
[  1/655] arm/altcycv_devkit (debug)                         Start
[  1/655] arm/altcycv_devkit (debug)                         Creating: bsp-builds/arm/altcycv_devkit.debug
[  2/655] arm/altcycv_devkit (no-posix)                      Start
[  2/655] arm/altcycv_devkit (no-posix)                      Creating: bsp-builds/arm/altcycv_devkit.no-posix
[  3/655] arm/altcycv_devkit (posix)                         Start
[  1/655] arm/altcycv_devkit (debug)                         Configuring
[  3/655] arm/altcycv_devkit (posix)                         Creating: bsp-builds/arm/altcycv_devkit.posix
[  2/655] arm/altcycv_devkit (no-posix)                      Configuring
[  4/655] arm/altcycv_devkit (posix-debug)                   Start
[  1/655] arm/altcycv_devkit (debug)                         Building
[  3/655] arm/altcycv_devkit (posix)                         Configuring
[  4/655] arm/altcycv_devkit (posix-debug)                   Creating: bsp-builds/arm/altcycv_devkit.posix-debug
[  2/655] arm/altcycv_devkit (no-posix)                      Building
[  5/655] arm/altcycv_devkit (posix-profiling)               Start
[  4/655] arm/altcycv_devkit (posix-debug)                   Configuring
[  3/655] arm/altcycv_devkit (posix)                         Building
 ....
[654/655] sparc/ngmp (posix-profiling)                       PASS
[654/655] sparc/ngmp (posix-profiling)                       Warnings:0  exes:0  objs:0  libs:0
[654/655] sparc/ngmp (posix-profiling)                       Finished (duration:0:01:49.002189)
[654/655] sparc/ngmp (posix-profiling)                       Status: Pass:  655  Fail:    0 (configure:0 build:0)
[655/655] sparc/ngmp (profiling)                             PASS
[655/655] sparc/ngmp (profiling)                             Warnings:0  exes:0  objs:0  libs:0
[655/655] sparc/ngmp (profiling)                             Finished (duration:0:01:260.002098)
[655/655] sparc/ngmp (profiling)                             Status: Pass:  655  Fail:    0 (configure:0 build:0)
[651/655] sparc/ngmp (no-posix)                              Cleaning: bsp-builds/sparc/ngmp.no-posix
[652/655] sparc/ngmp (posix)                                 Cleaning: bsp-builds/sparc/ngmp.posix
[653/655] sparc/ngmp (posix-debug)                           Cleaning: bsp-builds/sparc/ngmp.posix-debug
[654/655] sparc/ngmp (posix-profiling)                       Cleaning: bsp-builds/sparc/ngmp.posix-profiling
[655/655] sparc/ngmp (profiling)                             Cleaning: bsp-builds/sparc/ngmp.profiling
Total: Warnings:31689  exes:6291  objs:793839  libs:37897
Failures:
 No failure(s)
Average BSP Build Time: 0:00:18.165000
Total Time 3:41:48.075006
Passes: 655   Failures: 0

$ /opt/rtems/5/bin/rtems-bsp-builder --build-path=/build/rtems \
          --rtems-tools=/opt/work/rtems/5 \
          --rtems=/opt/work/chris/rtems/kernel/rtems.git \
          ----log=lpc-log \
          --bsp=arm/lpc2362,arm/lpc23xx_tli800 \
          --build=tests \
          --jobs=5/12
RTEMS Tools Project - RTEMS Kernel BSP Builder, 5.not_released
BSPS(s): arm/lpc2362, arm/lpc23xx_tli800
Cleaning: bsp-builds
[1/2] arm/lpc2362 (tests)        Start
[1/2] arm/lpc2362 (tests)        Creating: bsp-builds/arm/lpc2362.tests
[2/2] arm/lpc23xx_tli800 (tests) Start
[2/2] arm/lpc23xx_tli800 (tests) Creating: bsp-builds/arm/lpc23xx_tli800.tests
[1/2] arm/lpc2362 (tests)        Configuring
[2/2] arm/lpc23xx_tli800 (tests) Configuring
[1/2] arm/lpc2362 (tests)        Building
[2/2] arm/lpc23xx_tli800 (tests) Building
[1/2] arm/lpc2362 (tests)        FAIL
[1/2] arm/lpc2362 (tests)        Warnings:74  exes:58  objs:1645  libs:74
[1/2] arm/lpc2362 (tests)        Finished (duration:0:01:31.708252)
[1/2] arm/lpc2362 (tests)        Status: Pass:    0  Fail:    2 (configure:0 build:2)
[2/2] arm/lpc23xx_tli800 (tests) FAIL
[2/2] arm/lpc23xx_tli800 (tests) Warnings:74  exes:51  objs:1632  libs:74
[2/2] arm/lpc23xx_tli800 (tests) Finished (duration:0:01:31.747582)
[2/2] arm/lpc23xx_tli800 (tests) Status: Pass:    0  Fail:    2 (configure:0 build:2)
[1/2] arm/lpc2362 (tests)        Cleaning: bsp-builds/arm/lpc2362.tests
[2/2] arm/lpc23xx_tli800 (tests) Cleaning: bsp-builds/arm/lpc23xx_tli800.tests
Total: Warnings:74  exes:109  objs:3277  libs:148
Failures:
   1 tests arm/lpc2362 build:
      configure: /opt/work/chris/rtems/kernel/rtems.git/configure --target\
      =arm-rtems5 --enable-rtemsbsp=lpc2362 --prefix=/opt/rtems/5\
      --enable-tests
     error: ld/collect2:0 error: math.exe section '.rodata' will not fit
            in region 'ROM_INT'; region 'ROM_INT' overflowed by 7284 bytes

   2 tests arm/lpc23xx_tli800 build:
      configure: /opt/work/chris/rtems/kernel/rtems.git/configure --target\
      =arm-rtems5 --enable-rtemsbsp=lpc23xx_tli800\
      --prefix=/opt/rtems/5 --enable-tests
     error: ld/collect2:0 error: math.exe section '.text' will not fit in
            region 'ROM_INT'; region 'ROM_INT' overflowed by 13972 bytes

Average BSP Build Time: 0:00:46.658257
Total Time 0:01:33.316514
Passes: 0   Failures: 2

11.5.1. Available BSP testers¶

You can list the available BSP testers with:

$ rtems-test --list-bsps
arm920
beagleboardxm
beagleboneblack
jmr3904-run
jmr3904
mcf5235
pc
psim-run
psim
realview_pbx_a9_qemu
sis-run
sis
xilinx_zynq_a9_qemu
xilinx_zynq_a9_qemu_smp
xilinx_zynq_zc706
xilinx_zynq_zc706_qemu
xilinx_zynq_zedboard

Some of the BSPs may appear more than once in the list. These are aliased BSP configurations that may use a different back-end. An example is the erc32 BSP. There is the erc32 tester which uses the GDB back-end and the erc32-run tester which uses the run command for erc32. We will show how to use rtems-test command with the erc32 BSP because it is easy to build an use.

11.5.2. Building RTEMS Tests¶

Build the RTEMS Kernel (See RTEMS Kernel) by cloning the repository, running the bootstrap procedure, building and finally installing the kernel. Be sure to enable tests by using --enable-tests option with configure after running bootstrap.

$ ../../rtems.git/configure --target=sparc-rtems5 \
                    --enable-tests --enable-rtemsbsp=erc32
$ make

Add the -j option to the make command with the number of cores to run a parallel build.

Building all the tests takes time and it uses more disk so be patient. When finished all the tests will have been built. Some BSPs may require a post-build process to be run on the RTEMS ELF executable to create an image suitable for execution. This can be built into the configuration script and the tester will perform a pre-test command to covert the executable to a suitable format for your target.

Before running all the tests it is a good idea to run the hello test. The hello test is an RTEMS version of the classic “Hello World” example and running it shows you have a working tool chain and build of RTEMS ready to run the tests. Using the run with the ERC32 BSP the command is:

$ sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe

*** BEGIN OF TEST HELLO WORLD ***
Hello World
*** END OF TEST HELLO WORLD ***

The run command is the GDB simulator without the GDB part.

Running the example using GDB:

$ sparc-rtems5-gdb sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe
GNU gdb (GDB) 7.12
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-linux-gnu --target=sparc-rtems5".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from
sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe...done.
(gdb) target sim
Connected to the simulator.
(gdb) load
(gdb) r
Starting program: sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe


*** BEGIN OF TEST HELLO WORLD ***
Hello World
*** END OF TEST HELLO WORLD ***
[Inferior 1 (process 42000) exited normally]
(gdb) q

The command r is used to debug set break points before issuing the GDB run command.

There are currently close to 500 separate tests and you can run them all with a single RTEMS Tester command.

11.5.3. Running the Tests¶

The rtems-test command line accepts a range of options. These are discussed later in the manual. Any command line argument without a – prefix is a test executable. You can pass more than one executable on the command line. If the executable is a path to a directory the directories under that path are searched for any file with a .exe extension. This is the default extension for RTEMS executables built within RTEMS.

To run the erc32 tests enter the following command from the top of the erc32 BSP build tree:

$ ~/development/rtems/test/rtems-tools.git/tester/rtems-test \
         --log=log_erc32_run \
         --rtems-bsp=erc32-run \
         --rtems-tools=$HOME/development/rtems/5 \
             sparc-rtems5/c/erc32/testsuites/samples
RTEMS Testing - Tester, 5.not_released
[ 1/13] p:0  f:0  u:0  e:0  I:0  B:0  t:0  i:0  | sparc/erc32: base_sp.exe
[ 2/13] p:0  f:0  u:0  e:0  I:0  B:0  t:0  i:0  | sparc/erc32: capture.exe
[ 3/13] p:0  f:0  u:0  e:0  I:0  B:0  t:0  i:0  | sparc/erc32: cdtest.exe
[ 4/13] p:0  f:0  u:0  e:0  I:0  B:0  t:0  i:0  | sparc/erc32: fileio.exe
[ 5/13] p:2  f:0  u:0  e:0  I:0  B:0  t:0  i:0  | sparc/erc32: hello.exe
[ 6/13] p:2  f:0  u:0  e:0  I:0  B:0  t:0  i:0  | sparc/erc32: cxx_iostream.exe
[ 8/13] p:2  f:0  u:0  e:0  I:0  B:0  t:2  i:0  | sparc/erc32: minimum.exe
[ 7/13] p:2  f:0  u:0  e:0  I:0  B:0  t:2  i:0  | sparc/erc32: loopback.exe
[ 9/13] p:3  f:0  u:0  e:0  I:0  B:0  t:3  i:0  | sparc/erc32: nsecs.exe
[10/13] p:3  f:0  u:0  e:0  I:0  B:0  t:3  i:0  | sparc/erc32: paranoia.exe
[11/13] p:4  f:0  u:0  e:0  I:0  B:0  t:3  i:0  | sparc/erc32: pppd.exe
[12/13] p:6  f:0  u:0  e:0  I:0  B:0  t:3  i:0  | sparc/erc32: ticker.exe
[13/13] p:6  f:0  u:0  e:0  I:0  B:0  t:3  i:0  | sparc/erc32: unlimited.exe
Passed:         7
Failed:         0
User Input:     0
Expected Fail:  0
Indeterminate:  0
Benchmark:      0
Timeout:        5
Invalid:        1
Total:         13
Average test time: 0:00:27.963000
Testing time     : 0:06:03.519012

• The RTEMS Tester’s test command. In this example we are using an absolute path.
• The --log option sends the output to a log file. By default only failed tests log the complete output.
• Select the erc32 BSP and use GDB.
• Path to the RTEMS tools so GDB can be found.
• Path to the erc32 BSP built with all tests to run. If you add subdirectories to the path specific tests can be run.
• The output has been shortened so it fits nicely here.
• The test results shows passes, fails, timeouts, and invalid results. In this run 13 tests passed and 5 tests timed out and 1 is invalid. The timeouts are probably due to the tests not having enough execute time to complete. The default timeout is 180 seconds and some of the interrupt tests need longer. The amount of time depends on the performance of your host CPU running the simulations.
• The output shows the average time per test and the total time taken to run all the tests.
• If the path to the testsuites was put to sparc-rtems5/c/erc32/testsuites instead of sparc-rtems5/c/erc32/testsuites/samples then all the executables would have been tested and not just those in samples.

This BSP requires the --rtems-tools option because the SPARC GDB is the sparc-rtems4.11-gdb command that is part of the RTEMS tools. Not every BSP will require this option so you will need to check the specifics of the BSP configuration to determine if it is needed.

The output you see is each test starting to run. The rtems-test command by default runs multiple tests in parallel so you will see a number start quickly and then new tests start as others finish. The output shown here is from an 8 core processor so the first 8 are started in parallel and the status shows the order in which they actually started, which is not 1 to 8.

The test start line shows the current status of the tests. The status reported is when the test starts and not the result of that test. A fail, timeout or invalid count changing means a test running before this test started failed, not the starting test. The status here has 7 tests passed, no failures, 5 timeouts and 1 invalid test.

[ 5/13] p:2  f:0  u:0  e:0  I:0  B:0  t:0  i:0  | sparc/erc32: hello.exe

• [ 5/13] indicates the test number, in this case test 5 of 13 tests.
• p is the passed test count (2 in this case)
• f is the failed test count (0 in this case)
• u is the count for test marked as “user-input” as they expect input from user
• e is the expected-fail count (tests that are expected to fail)
• I is the count for tests the results of which are indeterminate
• B is the count for benchmarked tests
• t is the timeout test count
• i is the invalid test count.
• sparc/erc32 is the architecture and BSP names.
• hello.exe is the executable name.

The test log records all the tests and results. The logging mode by default only provides the output history if a test fails, times out, or is invalid. The time taken by each test is also recorded.

The tests must complete in a specified time or the test is marked as timed out. The default timeout is 3 minutes and can be globally changed using the --timeout command line option. The time required to complete a test can vary. When simulators are run in parallel the time taken depends on the specifics of the host machine being used. A test per core is the most stable method even though more tests can be run than available cores. If your machine needs longer or you are using a VM you may need to lengthen the timeout.

11.5.4. Test Status¶

Tests can be marked with one of the following:

• Pass
• Fail
• User-input
• Expected-fail
• Indeterminate
• Benchmark
• Timeout
• Invalid

The RTEMS console or stdout output from the test is needed to determine the result of the test.

11.5.5. Logging¶

The following modes of logging are available:

• All (all)
• Failures (failures)
• None (none)

The mode is controlled using the command line option --log-mode using the values listed above.

[ 11/472] p:9   f:0   t:0   i:1   | m68k/mcf5235: imfs_fslink.exe
> gdb: ..../bin/m68k-rtems4.11-gdb -i=mi --nx --quiet ..../imfs_fslink.exe
> Reading symbols from ..../fstests/imfs_fslink/imfs_fslink.exe...
> done.
> target remote | m68k-bdm-gdbserver pipe 003-005
> Remote debugging using | m68k-bdm-gdbserver pipe 003-005
> m68k-bdm: debug module version 0
> m68k-bdm: detected MCF5235
> m68k-bdm: architecture CF5235 connected to 003-005
> m68k-bdm: Coldfire debug module version is 0 (5206(e)/5235/5272/5282)
> Process 003-005 created; pid = 0
> 0x00006200 in ?? ()
> thb *0xffe254c0
> Hardware assisted breakpoint 1 at 0xffe254c0
> continue
> Continuing.
]
]
] External Reset
]
] ColdFire MCF5235 on the BCC
] Firmware v3b.1a.1a (Built on Jul 21 2004 17:31:28)
] Copyright 1995-2004 Freescale Semiconductor, Inc.  All Rights Reserved.
]
] Enter 'help' for help.
]
> Temporary breakpoint
> 1, 0xffe254c0 in ?? ()
> load
> Loading section .text, size 0x147e0 lma 0x40000
> Loading section .data, size 0x5d0 lma 0x547e0
> Start address 0x40414, load size 85424
> Transfer rate: 10 KB/sec, 1898 bytes/write.
> b bsp_reset
> Breakpoint 2 at 0x41274: file ..../shared/bspreset_loop.c, line 14.
> continue
> Continuing.
] dBUG>
]
] *** FILE SYSTEM TEST ( IMFS ) ***
] Initializing filesystem IMFS
]
]
] *** LINK TEST ***
] link creates hardlinks
] test if the stat is the same
] chmod and chown
] unlink then stat the file
] *** END OF LINK TEST ***
]
]
] Shutting down filesystem IMFS
] *** END OF FILE SYSTEM TEST ( IMFS ) ***
> Breakpoint
> 2, bsp_reset () at ..../m68k/mcf5235/../../shared/bspreset_loop.c:14
> 14    {
Result: passed     Time: 0:00:10.045447

11.5.6. Reporting¶

The RTEMS Tester supports output in a machine parsable format. This can be enabled using the options “–report-path” and “–report-format”. Currently, JSON output is supported using these options like so: ‘–report-path=”report” –report-format=json’

This will produce a file “report.json” that contains output equivalent to the “failure” logging mode.

11.5.7. Running Tests in Parallel¶

The RTEMS Tester supports parallel execution of tests by default. This only makes sense if the test back-end can run in parallel without resulting in resource contention. Simulators are an example of back-ends that can run in parallel. A hardware debug tool like a BDM or JTAG pod can manage only a single test at once so the tests need to be run one at a time.

The test framework manages the test jobs and orders the output in the log in test order. Output is held for completed tests until the next test to be reported has finished.

11.5.8. Command Line Help¶

The rtems-test command line accepts a range of options. You can review the available option by the --help option:

RTEMS Tools Project (c) 2012-2014 Chris Johns
Options and arguments:
--always-clean               : Always clean the build tree, even with an error
--debug-trace                : Debug trace based on specific flags
--dry-run                    : Do everything but actually run the build
--force                      : Force the build to proceed
--jobs=[0..n,none,half,full] : Run with specified number of jobs, default: num CPUs.
--keep-going                 : Do not stop on an error.
--list-bsps                  : List the supported BSPs
--log file                   : Log file where all build output is written to
--macros file[,file]         : Macro format files to load after the defaults
--no-clean                   : Do not clean up the build tree
--quiet                      : Quiet output (not used)
--report-path                : Report output base path (file extension will be added)
--report-format              : Formats in which to report test results: json
--log-mode                   : Log modes, failures (default),all,none
--rtems-bsp                  : The RTEMS BSP to run the test on
--rtems-tools                : The path to the RTEMS tools
--target                     : Set the target triplet
--timeout                    : Set the test timeout in seconds (default 180 seconds)
--trace                      : Trace the execution
--warn-all                   : Generate warnings