RTEMS User Manual (6.9e8141c).¶

2.1.1. Host Computer¶

The host computer is a computer you use to develop applications. It runs all your tools, editors, documentation viewers, etc. You need a native C, C++, and Python development environment. The following procedure assumes you have installed and configured your host operating system. It also assumes you have installed any dependent packages needed when building the tools and the kernel. Please make sure you can build native C/C++ applications on your host computer. You must be able to build native Python C modules as some RTEMS tools contain these modules. Usually, you have to install a Python development package for this. The Python scripts of the RTEMS Project expect on POSIX systems that a python command is available [1]. Please have a look at the Host Computer chapter for the gory details. In particular Microsoft Windows users should do this.

2.1.2. Selecting a BSP¶

If you are new to RTEMS and you are looking to try RTEMS then the best suited Board Support Package (BSP) is the SPARC ERC32 (erc32). The SPARC ERC32 BSP has a robust simulator that runs the example and test executables on your host computer. This Quick Start guide will build the erc32 BSP and run RTEMS tests executables in the simulator. The ERC32 BSP is a SPARC architecture BSP so the tool suite name is sparc-rtems5.

If you are looking for a hardware target to run RTEMS on we recommend the BeagleBone Black (beagleboneblack) BSP. The BeagleBone Black support includes the RTEMS BSD Library (libbsd) and networking. The BeagleBone Black BSP is an ARM architecture BSP so the tool suite name is arm-rtems5.

2.1.3. Selecting a Version of RTEMS¶

In the examples of this manual we will often refer to a specific version of RTEMS, which will usually be the version that accompanied the publication of this documentation manual. That may not be the appropriate version for you to use, for example, it may be too old (or too new) depending on what you are trying to do. If you’re not sure what version to use, we generally recommend using the most recent release or the development head (master), and you may want to consult with the same version of the documentation. We hope that newer is better.

An RTEMS release involves the creation of a single downloadable file, normally a compressed tarball, that packages the source of all the repositories in a state consistent with the time the release is created. A release branch is a git branch pushed to the repositories named with the numeric identifier of the branch. A release branch release is a git tag on a release branch with the tags pushed to the repositories.

Numbering for RTEMS versions beginning with RTEMS 5 uses a format as follows. The master branch has the version N.0.0 with N being the next major release number. The first release of this series has the version number N.1.0. and there is exactly one commit with this version number in the corresponding repository. The first bugfix release (minor release) of this series will have the version number N.2.0. The release branch will have the version number N.M.1 with M being the last minor release of this series.

For example:

• 5.0.0 is the version number of the development master for the 5 series.

• 5.1.0 is the first release of the 5 series.

• 5.1.1 is the version number of the 5 series release branch right after the 5.1.0 release until 5.2.0 is released.

• 5.2.0 is the first bugfix release of the 5 series

• 5.2.1 is the version number of the 5 series release branch right after the 5.2.0 release until 5.3.0 is released.

• 6.0.0 is the version number of the development master for the 6 series.

RTEMS development tools use N as the version number and are expected to work with all releases and the release branch of the N series. So to build tools for compiling RTEMS version number 5.1.0 for SPARC use sparc-rtems5. Despite the number not increasing, the tools may change within a release branch, for example the tools packaged with 5.1.1 still use the sparc-rtems5 moniker, but are likely not the same as the tools used in version 5.1.0. This tool mismatch can be a source of confusion. Be sure to use the toolchain that matches your release.

2.3.1. Releases¶

You can download the source archives for a released RTEMS version from RTEMS’ servers. Releases can be view at https://ftp.rtems.org/pub/rtems/releases with the releases listed as a series under a release’s major number. For RTEMS 5.1 the release series is 5 and the release path is https://ftp.rtems.org/pub/rtems/releases/6/6.0.

To work with the archives of a released RTEMS version, simply replace the version number 5 used throughout this chapter with the version number you selected, e.g. sparc-rtems4.11, sparc-rtems6, and so on.

Download and unpack using the curl and tar command with these commands:

mkdir -p $HOME/quick-start/src
cd $HOME/quick-start/src
curl https://ftp.rtems.org/pub/rtems/releases/6/6.0/sources/rtems-source-builder-6.0.tar.xz | tar xJf -

If curl does not work consider using wget or a browser.

The RSB is unpacked under the path rtems-source-builder-6.0. Rename this to rsb to get shorter paths during the tool suite build. To do this run these commands:

cd $HOME/quick-start/src
mv rtems-source-builder-6.0 rsb

If you wish to build the RTEMS kernel from source obtain the RTEMS kernel sources:

cd $HOME/quick-start/src
curl https://ftp.rtems.org/pub/rtems/releases/6/6.0/sources/rtems-6.0.tar.xz | tar xJf -

2.3.2. Git¶

Alternatively, clone the Git repositories into $HOME/quick-start/src.

A Git repository clone gives you some flexibility with the added complexity of needing to use a Git branch to build a released version. With Git you can switch between branches to try out different RTEMS versions and you have access to the RTEMS source history. The RTEMS Project welcomes contributions. The Git repositories enable you to easily create patches and track local changes.

You can clone the Git repository to get all versions of RTEMS including the development head. Release branches in Git are kept stable however they may differ from a release’s source archive.

mkdir -p $HOME/quick-start/src
cd $HOME/quick-start/src
git clone https://gitlab.rtems.org/rtems/tools/rtems-source-builder.git rsb
git clone https://gitlab.rtems.org/rtems/rtos/rtems.git

The rsb repository clone contains the RTEMS Source Builder (RSB). We clone it into rsb to get shorter paths during the tool suite build. The rtems repository clone contains the RTEMS sources. These two repositories are enough to get started. There are more repositories available.

2.3.3. Offline Download¶

If you have limited Internet access you can download the source before you start building. If you are permanently connected to the Internet you do not need to do this and the sources will be automatically download on demand when needed.

Once the sources have been downloaded you could disconnect your host computer from the Internet. It is no longer required to work with RTEMS. To download the sources to build the ERC 32 BSP before building run the following commands:

cd $HOME/quick-start/src/rsb/rtems
../source-builder/sb-set-builder --source-only-download 6/rtems-sparc

This command should output something like this (omitted lines are denoted by ...):

RTEMS Source Builder - Set Builder, 6 (5e449fb5c2cb)
Build Set: 6/rtems-sparc
Build Set: 6/rtems-autotools.bset
Build Set: 6/rtems-autotools-internal.bset
...
download: https://gitlab.rtems.org/rtems-tools/snapshot/rtems-tools-90342feb4dd63d188ce945adfb0a769...<see log> -> sources/rtems-tools-90342feb4dd63d188ce945adfb0a7694a42a65cd.tar.bz2
...
Build Sizes: usage: 0.000B total: 264.228MB (sources: 264.186MB, patches: 43.468KB, installed 0.000B)
Build Set: Time 0:06:34.357125

If you encounter errors, check your internet connection, firewall settings, virus scanners and the availability of the download servers.

2.4.1. Creating a Tool Archive¶

2.4.2. Need for RTEMS-Specific Cross-Compiler¶

New users are often confused as to why they cannot use their distribution’s cross-compiler for their target on RTEMS, e.g., the riscv64-linux-gnu or the arm-none-eabi-gcc. Below mentioned are some of the reasons for using the RTEMS cross-compiler.

Correct configuration of Newlib

Newlib is a C standard library implementation intended for use on embedded systems. Most of the POSIX and libc support for RTEMS is derived from Newlib. The RTEMS cross-compiler configures Newlib correctly for RTEMS.

Threading in GCC support libraries

Several threading packages in GCC such as Go threads (libgo), OpenMP (libgomp), and OpenACC need to be customized according to RTEMS. This is done by the RTEMS specific cross-compiler.

Provide preprocessor define __rtems__

The __rtems__ preprocessor define is used to provide conditional code compilation in source files that are shared with other projects e.g. in Newlib or imported code from FreeBSD.

Multilib variants to match the BSP

RTEMS configures GCC to create separate runtime libraries for each supported instruction set, floating point unit, vector unit, word size (e.g. 32-bit and 64-bit), endianness, ABI, processor errata workarounds, and so on in the architecture. These libraries are termed as Multilib variants. Multilib variants to match the BSP are set by selecting a specific set of machine options using the RTEMS cross-compiler.

2.4.3. Project Sandboxing¶

Project specific sandboxes let you have a number of projects running in parallel with each project in its own sandbox. You simply have a prefix per project and under that prefix you create a simple yet repeatable structure.

As an example lets say I have a large disk mounted under /bd for Big Disk. As root create a directory called projects and give the directory suitable permissions to be writable by you as a user.

Lets create a project sandbox for my Box Sorter project. First create a project directory called /bd/projects/box-sorter. Under this create rtems and under that create rtems-6.9e8141c. Under this path you can follow the released-version procedure to build a tool set using the prefix of /bd/projects/box-sorter/rtems/6.9e8141c. You are free to create your project specific directories under /bd/projects/box-sorter. The top level directories would be:

/bd/projects

Project specific development trees.

/bd/projects/box-sorter

Box Sorter project sandbox.

/bd/projects/box-sorter/rtems/6.9e8141c

Project prefix for RTEMS 6.9e8141c compiler, debuggers, tools and installed Board Support Package (BSP).

A variation is to use the --without-rtems option with the RSB to not build the BSPs when building the tools and to build RTEMS specifically for each project. This lets you have a production tools installed at a top level on your disk and each project can have a specific and possibly customised version of RTEMS. The top level directories would be:

/bd/rtems

The top path to production tools.

/bd/rtems/6.9e8141c

Production prefix for RTEMS 6.9e8141c compiler, debuggers and tools.

/bd/projects

Project specific development trees.

/bd/projects/box-sorter

Box Sorter project sandbox.

/bd/projects/box-sorter/rtems

Box Sorter project’s custom RTEMS kernel source and installed BSP.

A further varation if there is an RTEMS kernel you want to share between projects is it to move this to a top level and share. In this case you will end up with:

/bd/rtems

The top path to production tools and kernels.

/bd/rtems/6.9e8141c

Production prefix for RTEMS 6.9e8141c.

/bd/rtems/6.9e8141c/tools

Production prefix for RTEMS 6.9e8141c compiler, debuggers and tools.

/bd/rtems/6.9e8141c/bsps

Production prefix for RTEMS 6.9e8141c Board Support Packages (BSPs).

/bd/projects

Project specific development trees.

/bd/projects/box-sorter

Box Sorter project sandbox.

Finally you can have a single set of production tools and RTEMS BSPs on the disk under /bd/rtems you can share between your projects. The top level directories would be:

/bd/rtems

The top path to production tools and kernels.

/bd/rtems/6.9e8141c

Production prefix for RTEMS 6.9e8141c compiler, debuggers, tools and Board Support Packages (BSPs).

/bd/projects

Project specific development trees.

/bd/projects/box-sorter

Box Sorter project sandbox.

The project sandoxing approach allows you move a specific production part into the project’s sandbox to allow you to customise it. This is useful if you are testing new releases. The typical dependency is the order listed above. You can test new RTEMS kernels with production tools but new tools will require you build the kernel with them. Release notes with each release will let know what you need to update.

If the machine is a central project development machine simply replace projects with users and give each user a personal directory.

2.5.1. RSB BSP Build¶

The RSB build of RTEMS does not use the RTEMS source we made ready. It uses the RSB source you downloaded in a previous section. If you are using a release RSB source archive the BSP built is the released kernel image. If you are using a Git clone of the RSB the BSP will be version referenced in the RSB clone.

To build the BSP with all the tests run this command:

cd $HOME/quick-start/src/rsb/rtems
../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/6 \
    --target=sparc-rtems6 --with-rtems-bsp=sparc/erc32 --with-rtems-tests=yes 6/rtems-kernel

This command should output something like:

RTEMS Source Builder - Set Builder, @rtems-ver-majminver@
Build Set: 6/rtems-kernel
config: tools/rtems-kernel-6.cfg
package: sparc-rtems6-kernel-erc32-1
building: sparc-rtems6-kernel-erc32-1
sizes: sparc-rtems6-kernel-erc32-1: 2.279GB (installed: 44.612MB)
cleaning: sparc-rtems6-kernel-erc32-1
reporting: tools/rtems-kernel-6.cfg -> sparc-rtems6-kernel-erc32-1.txt
reporting: tools/rtems-kernel-6.cfg -> sparc-rtems6-kernel-erc32-1.xml
installing: sparc-rtems6-kernel-erc32-1 -> $BASE/
cleaning: sparc-rtems6-kernel-erc32-1
Build Set: Time 0:03:09.896961

The RSB BSP build can be customised with following RSB command line options:

--with-rtems-tests:

Build the test suite. If yes is provided all tests in the testsuite are build. If no is provided no tests are built and if samples is provided only the sample executables are built, e.g. --with-rtems-tests=yes. The test executables are install under the BSP in the tests directory and you can execute them with the tester and run command.

--with-rtems-smp:

Build with SMP support. The BSP has to have SMP support or this option will fail with an error.

--with-rtems-legacy-network:

Build the legacy network software. We recommend you use the current network support in the RTEMS BSP Library (libbsd) unless you need to maintain a legacy product. Do not use the legacy networking software for new developments.

--with-rtems-bspopts:

Build the BSP with BSP specific options. This is an advanced option. Please refer to the BSP specific details in the Board Support Packages (BSPs) of this manual or the BSP source code in the RTEMS source directory. To supply a list of options quote then list with ", e.g. --with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"

If you have built a BSP with the RSB, you can move on to Test a Board Support Package (BSP).

2.5.2. Manual BSP Build¶

We manually build the BSP in four steps. The first step is to set your path. Prepend the RTEMS tool suite binary directory to your $PATH throughout the remaining steps. Run the command:

export PATH=$HOME/quick-start/rtems/6/bin:"$PATH"

Check your installed tools can be found by running:

command -v sparc-rtems6-gcc && echo "found" || echo "not found"

The output should be:

found

If not found is printed the tools are not correctly installed or the path has not been correctly set. Check the contents of the path $HOME/quick-start/rtems/6/bin manually and if sparc-rtems6-gcc is present the path is wrong. If the file cannot be found return to Install the Tool Suite and install the tools again.

The second step is to configure the BSP. There are various BSP build configuration options available. Some options are BSP-specific. Each section in the INI-style configuration file config.ini instructs the build system to build a particular BSP variant (sparc/erc32 in our case). We enable the build of the tests with the BUILD_TESTS = True option and use default values for everything else. For detailed information about the BSP build system, see BSP Build System.

cd $HOME/quick-start/src/rtems
echo "[sparc/erc32]" > config.ini
echo "BUILD_TESTS = True" >> config.ini
./waf configure --prefix=$HOME/quick-start/rtems/6

The first invocation of ./waf needs a bit of time (e.g. 10 seconds) since an internal cache file is populated. This command should output something like this. In this output the base directory $HOME/quick-start was replaced by $BASE.

Setting top to                           : $BASE/quick-start/src/rtems
Setting out to                           : $BASE/quick-start/src/rtems/build
Configure board support package (BSP)    : sparc/erc32
Checking for program 'sparc-rtems6-gcc'  : $BASE/quick-start/rtems/6/bin/sparc-rtems6-gcc
Checking for program 'sparc-rtems6-g++'  : $BASE/quick-start/rtems/6/bin/sparc-rtems6-g++
Checking for program 'sparc-rtems6-ar'   : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar
Checking for program 'sparc-rtems6-ld'   : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ld
Checking for program 'ar'                : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar
Checking for program 'g++, c++'          : $BASE/quick-start/rtems/6/bin/sparc-rtems6-g++
Checking for program 'ar'                : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar
Checking for program 'gas, gcc'          : $BASE/quick-start/rtems/6/bin/sparc-rtems6-gcc
Checking for program 'ar'                : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar
Checking for program 'gcc, cc'           : $BASE/quick-start/rtems/6/bin/sparc-rtems6-gcc
Checking for program 'ar'                : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar
Checking for asm flags '-MMD'            : yes
Checking for c flags '-MMD'              : yes
Checking for cxx flags '-MMD'            : yes
Checking for program 'rtems-bin2c'       : $BASE/quick-start/rtems/6/bin/rtems-bin2c
Checking for program 'gzip'              : /usr/bin/gzip
Checking for program 'rtems-ld'          : $BASE/quick-start/rtems/6/bin/rtems-ld
Checking for program 'rtems-syms'        : $BASE/quick-start/rtems/6/bin/rtems-syms
Checking for program 'xz'                : $BASE/anaconda3/bin/xz
'configure' finished successfully (0.414s)

Building the BSP is the third step.

cd $HOME/quick-start/src/rtems
./waf

This command should output something like this (omitted lines are denoted by …).

Waf: Entering directory `$BASE/quick-start/src/rtems/build'
Waf: Leaving directory `$BASE/quick-start/src/rtems/build'
'build' finished successfully (0.085s)
Waf: Entering directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
[   1/4093] Compiling bsps/shared/dev/serial/mc68681_reg2.c
[   2/4093] Compiling bsps/shared/dev/rtc/mc146818a_ioreg.c
[   3/4093] Compiling bsps/shared/dev/flash/am29lv160.c
    ...
[4093/4093] Processing link: build/sparc/erc32/testsuites/libtests/dl01/dl01-tar.o build/sparc/erc32/testsuites/libtests/dl01/init.o build/sparc/erc32/testsuites/libtests/dl01/dl-load.o build/sparc/erc32/testsuites/libtests/dl01/dl01-sym.o -> build/sparc/erc32/testsuites/libtests/dl01.exe
Waf: Leaving directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
'build_sparc/erc32' finished successfully (2m14.111s)

The last step is to install the BSP.

cd $HOME/quick-start/src/rtems
./waf install

This command should output something like this (omitted lines are denoted by …). In this output the base directory $HOME/quick-start was replaced by $BASE.

Waf: Entering directory `$BASE/quick-start/src/rtems/build'
Waf: Leaving directory `$BASE/quick-start/src/rtems/build'
'install' finished successfully (0.081s)
Waf: Entering directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
+ install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/libchip/am29lv16.h (from bsps/include/libchip/am29lv1.h)
+ install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/libchip/mc146818a.h (from bsps/include/libchip/mc146818a.h)
+ install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/libchip/mc68681.h (from bsps/include/libchip/mc68681.h))
...
+ install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/rtems/score/watchdogticks.h (from cpukit/include/rtems/score/watchdogticks.h)
+ install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/rtems/score/wkspace.h (from cpukit/include/rtems/score/wkspace.h)
+ install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/rtems/score/wkspacedata.h (from cpukit/include/rtems/score/wkspacedata.h)
Waf: Leaving directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
'install_sparc/erc32' finished successfully (1.834s))

2.8.1. RTEMS Packages¶

RTEMS Packages are source packages the RSB build to run on RTEMS. An installed package is a set of header files and libraries. Your application include the packages header files to make calls to the package’s code and include the libraries in it’s linker options.

RTEMS packages can be part of the RTEMS Project or they can be external packages from 3rd parties. RTEMS Project packages include the BSPs and BSD Library package called libbsd. External 3rd party packages include networking such has curl or libcurl to graphics libraries.

Packages can depend on other packages and need to be build in the corret order. For example the FreeBSD Library package depends on the BSP package and a 3rd party library such as curl depends on the FreeBSD Library package. We call this layering a vertical software stack.

RTEMS applications are cross-compiled and this adds complexity when building libraries of code. RTEMS Packages build with the RSB manage this complexity for you.

Package are libraries so they will not be linked into your application until you make calls to the the code and add the library to your application’s linker command line.

2.8.2. BSP Stack Build¶

A BSP stack build is a single command that uses the RSB to build a BSP software stack of:

• Tool suite

• BSP

• Packages

The packages built depend on the BSP and the default will build all packages for a BSP.

cd $HOME/quick-start/src/rsb/rtems
../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
    --with-rtems-tests=yes bsps/erc32

This command should output something like this:

RTEMS Source Builder - Set Builder, 5.1.0
Build Set: bsps/erc32
Build Set: 5/rtems-sparc.bset
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-freebsd12.1-1
building: autoconf-2.69-x86_64-freebsd12.1-1
sizes: autoconf-2.69-x86_64-freebsd12.1-1: 7.505MB (installed: 0.000B)
...
building: protobuf-2.6.1-sparc-rtems5-1
sizes: protobuf-2.6.1-sparc-rtems5-1: 228.079MB (installed: 84.408MB)
cleaning: protobuf-2.6.1-sparc-rtems5-1
reporting: net/protobuf-2.6.1-1.cfg -> protobuf-2.6.1-sparc-rtems5-1.txt
reporting: net/protobuf-2.6.1-1.cfg -> protobuf-2.6.1-sparc-rtems5-1.xml
staging: protobuf-2.6.1-sparc-rtems5-1 -> $HOME/quick-start/src/rsb/rtems/build/tmp/sb-500-staging
cleaning: protobuf-2.6.1-sparc-rtems5-1
Build Set: Time 0:00:23.564992
Build Set: Time 0:02:27.380299
installing: bsps/erc32 -> $HOME/quick-start/rtems/
clean staging: bsps/erc32
Staging Size: 1.372GB
Build Set: Time 0:24:17.83979

The RSB BSP build can be customised with following RSB command line options:

--with-rtems-tests:

Build the test suite. If yes is provided all tests in the testsuite are build. If no is provided no tests are built and if samples is provided only the sample executables are built, e.g. --with-rtems-tests=yes.

--with-rtems-smp:

Build with SMP support. The BSP has to have SMP support or this option will fail with an error.

--with-rtems-bspopts:

Build the BSP with BSP specific options. This is an advanced option. Please refer to the BSP specific details in the Board Support Packages (BSPs) of this manual or the BSP source code in the RTEMS source directory. To supply a list of options quote then list with ", e.g. --with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"

Only a limited number of BSPs have RSB support to build as a software stack. To see which BSPs are supported run this command:

cd $HOME/quick-start/src/rsb/rtems
../source-builder/sb-set-builder --list-bsets | grep bsps

2.8.3. Package Build¶

Packages are built using RSB build sets. A build set is a set of builds need to build a packages. The build steps can be dependencies a package has or it could be a stack of software to provide specific functionality, i.e. a build set can be a list of build sets. To view the avaliable build sets run this command:

cd $HOME/quick-start/src/rsb/rtems
../source-builder/sb-set-builder --list-bsets

RTEMS package naming is based on the naming FreeBSD uses in its ports collection.

This Quick Start Guide will build the BSD Library or 5/rtems-libbsd.

An RTEMS package is hosted on RTEMS so the tool suite name needs to be supplied using the --host option, e.g. --host=sparc-rtem5. The BSP needs to be provided using the --with-rtems-bsp option, e.g. --with-rtems-bsp=erc32. The commands to build libbsd for the erc32 BSP are:

cd $HOME/quick-start/src/rsb/rtems
../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
  --host=sparc-rtems5 --with-rtems-bsp=erc32 5/rtems-libbsd

This command should output something like this:

RTEMS Source Builder - Set Builder, 5.1.0
Build Set: 5/rtems-libbsd
config: tools/rtems-libbsd-5.cfg
package: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
building: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
sizes: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1: 1.199GB (installed: 116.541MB)
cleaning: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
reporting: tools/rtems-libbsd-5.cfg -> rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1.txt
reporting: tools/rtems-libbsd-5.cfg -> rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1.xml
installing: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1 -> $HOME/quick-start/rtems/5
cleaning: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
Build Set: Time 0:00:51.898231

2.9.1. Installing Dependencies¶

You need tools for your host’s operating system to build the RTEMS tool suite from source. Please have a look at the Host Computer chapter for the instructions to install the tools for your OS.

2.9.2. Choosing an installation prefix¶

The term prefix refers to the path on your computer where the software is to be installed. You can refer to the Prefix section for details on choosing an installation prefix.

2.9.3. Downloading the Sources¶

We will be using Git to clone the sources for RTEMS and RSB. This is the preferred way if you are planning to make contributions to the RTEMS project.

Please refer to the Git section for instructions on obtaining sources using Git.

2.9.4. Installing the Tool Suite¶

The Tools suite is the collection of tools required to build the BSP. This includes the compiler, debugger, assembler and other tools. These tools are architecture-specific. We will be installing the SPARC tool suite since we are building a SPARC based BSP.

Please refer to the Install the Tool Suite section for instructions on building and installing the tool suite. Remember to use the current version associated with the RTEMS development head, see Selecting a Version of RTEMS.

2.9.5. Building the Board Support Package¶

There are two ways of building a BSP. We could either ask RSB to build the BSP or manually build it. In this section will we be building it manually. Please refer the Manual BSP Build section for the instructions.

2.9.6. Testing the Board Support Package¶

Testing is an essential part of RTEMS development process. The main reason for choosing the SPARC erc32 BSP is that, it has very good simulator support. This will allow you to test your changes without the need for SPARC hardware.

Please refer to Test a Board Support Package (BSP) for instructions on testing the BSP.

2.9.7. Prove You Can Work On RTEMS¶

This section is only for students interested in Google Summer of Code.

You have to finish the following task to prove that you can work on RTEMS.

Modify the hello world example to include a new different print statement. Something like “Hello from The Dark Side!”. Then send us enough to prove to us that you did this. We want to know you can work with RTEMS.

Create a patch of your changes and send it to Developers Mailing List along with the screenshot of the output.

If you followed this guide, this hello world modification will likely need to be made in $HOME/quick-start/src/rtems/testsuites/samples/hello/init.c. To test your changes, you have to build the BSP again. This could be done by running make in the BSP build directory.

cd $HOME/quick-start/src/rtems
./waf

If you are happy with your changes you can commit the changes and send the patch to Developers Mailing List.

2.9.8. Creating and Sending Patches¶

Before sending patches, make sure that the changes you have made conforms to RTEMS coding standards. You can refer to Contributing section for instruction on creating and sending patches.

Here are a few pointers to keep in mind while creating the patches.

• Make sure not to commit changes in the master branch. This is to avoid merge conflicts when you are pulling the latest changes from the remote branch.

• Avoid trailing whitespace errors.

• The author name of the patch is your full name.

• The author email of the patch is your valid email address.

• Ensure that your patches build before sending them for review.

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. Discord¶

The RTEMS Discord server is available at https://www.rtems.org/discord

We have several channels available for discussion please be kind. The purpose of each channel is listed in thier discriptions.

For support with GitLab there is also the #gitlab-support channel.

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, see Configuring a System chapter of the RTEMS Classic API Guide. 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. Creating Good Bug Reports¶

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

• Click the “Select project to create issue” button for the relevant repository.

• Click the New Issue button for the selected project repository.

• Provide a useful single line Summary in the Title.

• Fill out a description with target details, reproduction steps, build environment, exact versions, etc. Use MarkDown 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. In addition, select the appropriate arch:: label if the bug is hardware-specific.

• 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 main branch. If it is not reproducible on main, 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 the Milestone to which this bug applies. It should be the nearest unreleased Milestone from the affected branch. Ask for help if you are not sure.

• Select a set of appropriate Labels for the issue.

• Select whether the issue is confidential. This is only expected in the potential context of security bugs.

• 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 submit it.

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

3.3.2. Preparing and Submitting Merge Requests¶

The RTEMS Project uses Git for version control and uses Gitlab for managing changes. Contributions are made by creating a Merge Request (MR) on Gitlab. The Gitlab merge request documentation comprehensively explains the concepts of using merge requests. RTEMS will only accept changes via a Merge Request. Most merge requests should have one or more Issues associated with them, unless it is a simple, isolated change. Please do not use merge requests to introduce new code, concepts, styles or to change existing behaviours such as APIs or internal interfaces. Please create an issue before you start the work so the community is aware of the changes coming. The merge requests can then focus on the details of the implementation and approval does not need to be about approval of change at a functional level.

We use project forks as the base of our workflow and outside of that there is no workflow we mandate. What works for one task or work package may not work for another. Complex tasks may affect a number of our GitLab Projects with issues and merge requests in a number of projects. You may want to use an Epic to bring work together.

With our GitLab instance, you fork a repo into your personal workspace and use that to manage your changes. This means you need to keep your forked project up to date. See the Gitlab forking workflow documentation <https://docs.gitlab.com/ee/user/project/merge_requests/authorization_for_merge_requests.html#forking-workflow> for details. If you are part of a team working on a change you can collaborate on merge requests <https://docs.gitlab.com/ee/user/project/merge_requests/allow_collaboration.html>. GitLab enforces branch naming rules and provides branch naming patterns <https://docs.gitlab.com/ee/user/project/repository/branches/#prefix-branch-names-with-issue-numbers> that simplifies code review and software change management. You can create merge requests from your fork <https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#when-you-work-in-a-fork> back to the upstream repository. We do not normally squash merge requests. A merge request with more than one commit should be buildable at each commit so a bisect of main does not break.

3.3.3. Checklist for Merge Requests¶

Check the following items before you publish your merge requests:

• The author name of each commit is a full name of the author.

• The author email of each commit is a valid email address for the author.

• 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 meaningful title which does not exceed 50 characters in one line. Use a “topic: The meaningful title” style. A topic could be the main component of the commit. Just have a look at existing commit messages.

• Each 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.

• Each patch contains no spelling mistakes and grammar errors.

• Each patch is easy to review. It changes one thing only and contains no unrelated changes. Format changes should be separated from functional changes.

• If commits correspond to Issues, the merge request should have “Close #X.” or “Update #X.” to update status once it is merged.

• Each patch builds. All RTEMS tests link with every patch.

• Each patch does not introduce new compiler warnings.

• Each patch does not introduce new test failures in existing tests.

3.3.4. Review Process¶

Merge requests sent to the RTEMS Gitlab undergo a public review process. At least two approvals are required before a merge request can be pushed to the RTEMS repository. It helps if you follow the Checklist for Merge Requests. An easy to review patch series which meets the quality standards of the RTEMS Project will be more likely to get integrated quickly.

The review process includes both objective and subjective feedback. You should reflect upon and consider all feedback before making or refusing changes. It is important to note that some feedback may be relevant at one point in time, but less relevant in the future. Also, what concerns one developer may not concern another. Just because you address all the feedback in one round of review does not mean your submission will be approved, as someone (even the same reviewer) may notice something that was not seen before. It is important to have patience, humility, and open-mindedness when engaging in open-source software review and approval processes. This is true for both contributors and reviewers.

Reviews should be conducted primarily via the GitLab interface using the in-line commenting feature. Follow-up comments to the same line should be threaded, while new comments should be added to the specific, relevant line of modified code. Although high-level comments about the entire patch set are allowed, the most useful commments are those that are specifically targeted to problematic lines of code.

3.3.5. Updating a Merge Request¶

As you make changes to your merge request through the review process, you will either be layering additional patches on top of your current patch set, or you will be rebasing your patch set. Either approach is acceptable, but remember that every patch in your patch set must pass continuous integration testing and adhere to the Checklist for Merge Requests. Most often, this means that you should rebase the patch set in your merge request to include the updates.

There are several ways you can rebase the patch set. The following is one suggested workflow:

# Before making changes, create a new local branch of your merge request. Make

your changes on this branch, so that you can always go back to your previous state. Always keep your original branch until you have pushed a new, clean version that supersedes it. Even then, you may want to keep your original branch around in case something went wrong that you did not notice, such as you accidentally removed a necessary commit while rebasing.

# Make and commit changes locally until you are satisfied with your code

# Interactively rebase your local branch using git rebase –interactive

to allow you to select the order of commits and to reword or fixup commits. One good strategy here is to reorder and fixup commits in one round and then reword them in a second round, so that you get your commits in the right order and shape you want before finalizing the patch descriptions.

# Force-push your local branch to your merge request branch on your fork. If

something goes wrong, you can revert back to your local version.

3.3.6. Rebasing a Merge Request¶

You can follow a similar process as Updating a Merge Request to rebase your merge request branch to an updated target branch, e.g., to pick up changes on main. In this case, after creating a local branch, use git pull –rebase stopping to fix merge conflicts along the way. If it gets out of hand, you can either abort the rebase or you can go back to your original branch.

When merge conflicts are too much to handle doing a rebase, you may instead like to create a fresh branch from main and then use git-cherry-pick to pull commits from your merge request branch on to the head of main. If you are having too much trouble, ask for help.

3.3.7. Approvers¶

Merge Request approvals must be from a code owner, identified by the CODEOWNERS file and by sub-groups beneath Approvers. Any one who has requested approval permission can approve a merge request. Once a patch series is approved for integration into the RTEMS code base it can be merged by anyone with merge rights, which may include an automated bot.

Approvers are volunteering their time so be polite. If you do not get a response to a merge request after five working days, please send a reminder on the merge request or send email to the Developers Mailing List.

3.3.8. 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 Developers 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 other developers 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.9. 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.1.1. Virtual Environment¶

Python3 provides virtual environment support. This is a great way to manage Python on a single host. You can have a number of virtual environments with a different mix of installed Python packages with different versions that do not clash.

Virtual environment always provide a python command. This makes it ideal if your host only provides Python3 and there is no default python command.

A virtual environment is created once and when you need to use it you activate it and when finished you deactivate it.

The following shows how to create a virtual environment using different methods. You can select the method that best suites you.

To create a virtual environment using the Python3 venv module:

python3 -m venv rtems-py

To create a virtual environment for a specific version of Python3 you can enter the command:

python3.7 -m venv rtems-py

You can also install the virtualenv package on your host if it is avaliable then enter the following create command:

virtualenv rtems-py

To activate the virtual environment:

. rtems-py/bin/activate

You will see your prompt change to reflect the virtual environment you have active. To check if you now have a python command enter:

type python

The output will be something similar to the following:

(rtems-py) $ type python
python is /home/chris/development/rtems-py/bin/python

4.1.2. Symbolic Link¶

If your host does not provide the python command you can add a symbolic link to it.

We suggest you add the symbolic link to a directory under your home directory adding that directory to your environment’s PATH variable. The following commands show how to do this:

cd
mkdir bin
cd bin
ln -s `command -v python3` python
export PATH=$HOME/bin:$PATH

4.1.3. Directly Invoking Python¶

It is valid to specifically invoke any python script directly. To do this simply prepend the specific version of python you wish to use. For example to run the waf build system command with Python3 use:

python3 ./waf

4.3.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.3.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 pax \
bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git

# dnf install yum-utils
# dnf config-manager --set-enabled PowerTools
# dnf update
# dnf groupinstall "Development Tools"
# dnf install python3 python3-pip python3-setuptools python3-devel
# dnf install texinfo spax
# alternatives --set python /usr/bin/python3

# 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 install build-essential g++ gdb unzip pax bison flex texinfo \
python3-dev python-is-python3 libpython2-dev libncurses5-dev zlib1g-dev \
ninja-build pkg-config

$ sudo apt-get install python git

# sudo apt-get install zlib1g-dev

# sudo zypper in -t pattern devel_C_C++ devel_python3

# sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 1

4.3.3. FreeBSD¶

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

# pkg install -y python
# pkg install -y gsed

For FreeBSD 13, you will need to install the packages listed above, as well as the following additional ones. They are:

# pkg install -y bison texinfo gmake binutils

FreeBSD’s default C compiler is LLVM and installing the host’s GCC compiler package may break building GCC. We recommend you do not install the GCC package and you use the default C compiler.

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

# pkg install -y mingw32-binutils mingw32-gcc
# pkg install -y mingw32-zlib mingw32-pthreads

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

Check if your kernel has a /dev/fd directory. If it does not we recommend you run as root the following command to speed up Python 3’s subprocess support:

# mount -t fdescfs none /dev/fd

The support speeds up closing file descriptors when creating subprocesses.

4.3.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.4.1. Python¶

Building GDB requires the installation of Python’s development libraries. Building GDB includes the Python runtime header Python.h and linking to the Python runtime libraries. The RSB detects a valid header and libraries before starting a GDB build.

It is recommended you run the RSB in a Python virtual environment. A virtual environment manages paths for you, provides a python executable mapped to the version the virtual environment is built with and a command to find the appropiate runtime header and library files GDB needs. Virtual environments make it easier to update Python to a newer version if this is needed.

Apple has removed support for Python’s development libraries from recent versions of MacOS as users can manage Python using the installer packages provided by the Python project.

To install:

1. Download a Python installer for MacOS from https://www.python.org/.

2. Run the installer and install Python.

3. Open a terminal and update your shell profile using the command Python provides. For Python 3.12 the command is:

   /Applications/Python\ 3.12/Update\ Shell\ Profile.command
   

   Check with:

   % type python3.12
   python3.12 is /Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12
   

4. Create a virtual environment:

   mkdir $HOME/development/rtems
   cd $HOME/development/rtems
   python3.12 -m venv py3.12
   

   Activate the virtual environment:

   . $HOME/development/rtems/py3.12/bin/activate
   

   You are now ready to the build the tools within the virtual environment.

4.4.2. Sonoma¶

The RSB is supported on Sonoma and Applie silicon.

4.4.3. Ventura¶

The RSB is supported on Ventura and Intel silicon.

4.4.4. Monterey¶

The RSB is supported on Ventura and Intel silicon.

4.4.5. Catalina¶

In the macOS Catalina 10.15 Release Notes Apple deprecated several scripting language runtimes such as Python 2.7. See also Xcode 11 Release Notes. Due to the deprecated Python 2.7 support, we recommend to install and use the latest Python 3 release from python.org.

4.4.6. Sierra¶

The RSB works on Sierra with the latest Xcode.

4.4.7. 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.5.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 released-version.

4.5.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.5.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.5.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.5.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.5.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-python3

• mingw-w64-x86_64-gcc

• flex

• git

• bison

• cvs

• diffutils

• make

• patch

• tar

• texinfo

• unzip

Install the packages using pacman:

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

The base installer executable puts the compiler you want to use in /mingw64/bin which needs to be added to the beginning of your PATH. You can do that for example by adding this line to the end of ${HOME}/.bashrc:

export PATH=/mingw64/bin:$PATH

You will also likely want to add to PATH the bin directory of the prefix where you plan to install RTEMS.

4.5.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/6.0 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/6.0
installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/6.0 <3>
installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/6.0
installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/6.0
installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/6.0
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>

8.1.1. Qemu A53¶

This BSP supports two variants, qemu_a53_ilp32 and qemu_a53_lp64. The basic hardware initialization is performed by the BSP. These BSPs support the GICv3 interrupt controller.

qemu-system-aarch64 -no-reboot -nographic -serial mon:stdio \
 -machine virt,gic-version=3 -cpu cortex-a53 -m 4096 -kernel example.exe

8.1.2. Qemu A72¶

This BSP supports two variants, qemu_a72_ilp32 and qemu_a72_lp64. The basic hardware initialization is performed by the BSP. These BSPs support the GICv3 interrupt controller.

8.1.3. Qemu Xilinx Versal¶

This BSP supports three variants: versal-qemu, versal-aiedge and versal-vck190. The basic hardware initialization is performed by the BSP. These BSPs support the GICv3 interrupt controller present in the Xilinx Versal Adaptive Compute Acceleration Platform (ACAP) systems. The BSPs currently only work when started in the secure mode.

8.1.4. Xilinx ZynqMP¶

This BSP family supports the following variants:

• zynqmp_qemu_ilp32

• zynqmp_qemu

• zynqmp_apu_ilp32

• zynqmp_apu

• zynqmp_cfc400x

Platform-specific hardware initialization is performed by ARM Trusted Firmware (ATF). Other basic hardware initialization is performed by the BSP. These BSPs support the GICv2 interrupt controller present in all ZynqMP systems. The zynqmp_apu BSP has been tested on zu2cg, zu3eg, and zu9cg chip variants and should also work on any other ZynqMP chip variant since the Processing Subsystem (PS) does not vary among chip variants other than the number of CPU cores available.

This BSP family has been tested on the following hardware:

• Avnet UltraZed-EG SOM

• Innoflight CFC-400X

• Trenz TE0802

• Xilinx ZCU102

build/aarch64/zynqmp_apu/testsuites/samples

$ aarch64-rtems@rtems-ver-major@-objcopy -Obinary ticker.exe ticker.bin
$ gzip -9 ticker.bin
$ mkimage -A arm64 -O rtems -T kernel -a 0x10000 -e 0x10000 -n RTEMS -d ticker.bin.gz rtems.img

Zynq-MP> fatload mmc 0:1 0x1000 rtems.img
Zynq-MP> bootm 0x1000

Pre-FSBL boot Started
Xilinx Zynq MP First Stage Boot Loader
Release 2020.2   Nov 18 2020  -  11:46:01
NOTICE:  ATF running on XCZU9EG/silicon v1/RTL5.1 at 0xfffea000
NOTICE:  BL31: v2.2(release):xilinx_rebase_v2.2_2020.1-10-ge6eea88b1
NOTICE:  BL31: Built : 12:28:45, Nov 17 2020

U-Boot 2020.01 (Jun 15 2021 - 14:24:32 +0000)

Model: ZynqMP ZCU102 Rev1.0
Board: Xilinx ZynqMP
DRAM:  4 GiB
PMUFW:  v1.1
EL Level:       EL2
Chip ID:        zu9eg
NAND:  0 MiB
MMC:   mmc@ff170000: 0
In:    serial@ff000000
Out:   serial@ff000000
Err:   serial@ff000000
Bootmode: SD_MODE1
Reset reason:   SOFT
Net:
ZYNQ GEM: ff0e0000, mdio bus ff0e0000, phyaddr 12, interface rgmii-id

Warning: ethernet@ff0e0000 (eth0) using random MAC address - 82:32:1d:80:d9:c9
eth0: ethernet@ff0e0000
Hit any key to stop autoboot:  0

ZynqMP> fatload mmc 0:1 0x1000 rtems.img
46669 bytes read in 27 ms (1.6 MiB/s)
ZynqMP> bootm 0x1000
## Booting kernel from Legacy Image at 00001000 ...
   Image Name:   RTEMS
   Image Type:   AArch64 RTEMS Kernel Image (gzip compressed)
   Data Size:    46605 Bytes = 45.5 KiB
   Load Address: 10000000
   Entry Point:  10000000
   Verifying Checksum ... OK
   Uncompressing Kernel Image
## Transferring control to RTEMS (at address 10000000) ...

*** BEGIN OF TEST CLOCK TICK ***
*** TEST VERSION: @rtems-version@.f381e9bab29278e4434b1a93e70d17a7562dc64c
*** TEST STATE: EXPECTED_PASS
*** TEST BUILD: RTEMS_POSIX_API RTEMS_SMP
*** TEST TOOLS: 10.3.1 20210409 (RTEMS 6, RSB ad54d1dd3cf8249d9d39deb1dd28b2f294df062d, Newlib eb03ac1)
TA1  - rtems_clock_get_tod - 09:00:00   12/31/1988
TA2  - rtems_clock_get_tod - 09:00:00   12/31/1988
TA3  - rtems_clock_get_tod - 09:00:00   12/31/1988
TA1  - rtems_clock_get_tod - 09:00:05   12/31/1988
TA2  - rtems_clock_get_tod - 09:00:10   12/31/1988
TA1  - rtems_clock_get_tod - 09:00:10   12/31/1988
TA1  - rtems_clock_get_tod - 09:00:15   12/31/1988
TA3  - rtems_clock_get_tod - 09:00:15   12/31/1988
TA2  - rtems_clock_get_tod - 09:00:20   12/31/1988
TA1  - rtems_clock_get_tod - 09:00:20   12/31/1988
TA1  - rtems_clock_get_tod - 09:00:25   12/31/1988
TA2  - rtems_clock_get_tod - 09:00:30   12/31/1988
TA1  - rtems_clock_get_tod - 09:00:30   12/31/1988
TA3  - rtems_clock_get_tod - 09:00:30   12/31/1988

*** END OF TEST CLOCK TICK ***

[ RTEMS shutdown ]

qemu-system-aarch64 -no-reboot -nographic -serial mon:stdio \
 -machine xlnx-zcu102 -m 4096 -kernel media01.exe -sd example.img

qemu-system-aarch64 -no-reboot -nographic -serial mon:stdio \
 -machine xlnx-zcu102 -m 4096 -kernel example.exe

8.1.5. Raspberry Pi 4B¶

The ‘raspberrypi4b’ BSP currently supports only the LP64 ABI. ILP32 is not supported. Raspberry pi 4B all variants and Raspberry Pi 400 are supported. The default bootloader which is used by the Raspbian OS or other OS can be used to boot RTEMS. SMP is currently not supported.

Raspberry Pi 4B has 2 types of interrupt controller, GIC-400 (GICv2) and ARM legacy generic controller. Both are supported.

The documentation says that enable_gic=1 is the default but that seems to be true only if device tree is present otherwise it reverts to the legacy interrupt controller. So set enable_gic=1 in the config.txt file to make sure gic is enable.

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

void uart_init(void)
{
  int rv;

  /* The optional devices are UART0, UART2, UART3, UART4, UART5. */
  rv =  raspberrypi_uart_init(UART0);
  assert(rv == 0);
}

#include <assert.h>
#include <bsp/raspberrypi-spi.h>

void spi_init(void)
{
  int rv;

  /*
   * The optional devices are raspberrypi_SPI0, raspberrypi_SPI3,
   * raspberrypi_SPI4, raspberrypi_SPI5, raspberrypi_SPI6.
   */
  rv =  raspberrypi_spi_init(raspberrypi_SPI0);
  assert(rv == 0);
}

void raspberrypi_watchdog_example()
{
  raspberrypi_watchdog_init();
  raspberrypi_watchdog_start(15000);

  raspberrypi_watchdog_reload();
  /* ... */
  raspberrypi_watchdog_reload();

  raspberrypi_watchdog_stop();
}

$ aarch64-rtems@rtems-ver-major@-objcopy -Obinary hello.exe kernel8.img

# Disable pull downs
gpio=22-27=np

# Enable jtag pins (i.e. GPIO22-GPIO27)
enable_jtag_gpio=1

8.3.1. bf537Stamp¶

TODO.

8.3.2. eZKit533¶

TODO.

8.3.3. TLL6527M¶

TODO.

8.4.1. pc386¶

This BSP supports a standard Intel/AMD PC on i386 and up CPUs. If run on a Pentium or above, the TSC register is used for timing calibration purposes rather than relying entirely on the i8254. Partial support is implemented for more modern PCs which do not have a complete complement of legacy peripherals.

The BSP is able to utilize up to 3 GB of available RAM and up to 16 CPUs. Hyper-threading is supported, but may not be detected by the BSP successfully.

There are several BSP variants provided which differ only in the target CPU optimization. The most general is pc386 which is tuned for i386. The pc486 variant is tuned for i486, pc585 is tuned for Pentium, pc586-sse is tuned for Pentium processor supporting SSE instructions. Finally pc686 is tuned for Pentium Pro processor, but generating only instructions for Pentium and pcp4 is tuned and generating instructions for Pentium4 processor including SSE3 instructions.

$ qemu-system-i386 -m 128 -no-reboot -append \
"--video=off --console=/dev/com1" -nographic -kernel ./hello.exe

$ sudo qemu-system-i386 -machine type=q35,accel=kvm -m 128 -no-reboot \
    -append "--video=off --console=/dev/com1" -nographic -kernel \
    ./dhrystone.exe