Deploying RTEMS

Tools Deployment
1

Deploying RTEMS

Deployment of RTEMS is a process you can use to make tools, header files and libraries available to a team, company or customers in a way that is controlled and repeatable. You can deploy a package for each hardware item you deliver or you can include the package in a larger software stack. A deploy-able software stack is built once per release and it is intended you build a single package all developers in a project or company can use.

Deployment does not define how you package the tools or how you control them. There are really good tools on a number of platforms you can use and what you use is best defined by you and the requirements of your systems, team and company. Examples are a simple tar file for a host, packaging system such as RPM, docker containers and installers like MSI on Windows.

If the RTEMS Deployment tool does not support a platform please discuss this with the RTEMS project. RTEMS Deployment is open and welcomes new packaging formats and build configurations.

Quick Start

If this post is too long and you want to get going the Deployment in the least number of commands post shows how to run deployment in a few commands.

Note: deployment is not used when developing RTEMS or packages for RTEMS.

Vertical Software Stack

An important part of deployment is building a number of packages for your project. These packages can be visualized as a vertical stack that depend on the layers below.

A vertical software stack is a series of packages built in a specific order to provide the functionality you need for your project. If for example your project needs networking you first need to building the tools such as gcc and ld then use those tools to build the kernel and finally the tools and kernel are used to build libbsd to give your project networking.

Moving up a vertical stack refines and specializes what is delivered. The tools will be able to build all BSPs in the architecture. The kernel will be built for one or more BSPs and finally libbsd will provide specific networking functional for the BSP and the target hardware. Deployment is not focused on the reuse of a package. It is focused on a controlled deliverable for your project and team.

BSPs

A package can contain a number of BSPs. An organization may support a number of different pieces of hardware and they can be included in a single package. Currently only a single architecture and its BSPs plus the same networking stack have been successfully packaged. There are limits in what can be combined.

A combined package of vertically stacked software for multiple BSPs can be visualized as the vertical stack on a Y-axis and the BSPs on the X-axis.

RSB Build-sets and Configurations

The RSB will combine the build-set (.bset) and configuration(.cfg) files from a config directory with the build-set and configuration files provided with the RSB. The config directory can be on any disk, or it can be part of a repository for a project or it could be generated as part of a larger more complex build system. The RSB’s sb-set-builder command will look for a config sub-directory and join it with it’s internal configuration directories.

This feature of the RSB lets you build specialized software stacks for custom configurations of RTEMS and it is not limited to the RTEMS Deployment tool.

Where to Install RTEMS

Deployment builds all the software pieces you need to create an application and these files, such as header files, libraries of code and a range of build configuration files are installed under the single path you provide.

The installation path is called the prefix. This is a historical name that comes from the original GNU tool configure command. It is easiest and simple to just think of the install path when you see prefix.

What is the right Install Path

There is no right or wrong install path. A number of factors effect the path you use. These can be the host operating system, a fast disk hardware or a shared network server path. You can have a number of different projects installed at the one time and the installs for your products or teams could run different versions of RTEMS. You can think of the install path or prefix as a tool you can use at the system level to manage and configuration control the different builds and version of RTEMS.

If you have more than one type of tools installed or more than one version decide on a path format that works for you. For example a path could be /opt/rtems/foo/6 and /opt/rtems/foo/7 or you could group by version, for example /opt/rtems6/foo and /opt/rtems/7/foo. The first alternative makes archiving a project easier because it naturally collects all the versions being used together.

You can decide on any path you like. A machine you have could have a large ZFS pool and so you might use /tank/opt/foobar/6.

RTEMS Documentation Install Paths

You will see in RTEMS documentation a number of different prefix paths are used. The writer of the documentation may have just copied the path they were using at the time and it is nothing more than a path they used.

The documented path may have a specific purpose. For example the Quick Start section of the RTEMS User Manual uses $HOME/development/rtems as a base path for the prefix and this is a deliberate choice to try and make those quick start commands always work. Your home directory is used because you will always have write permission and you do not need to get or use administrator privileges. On MacOS is the best place as MacOS is a single user operating system. MSYS2 on Windows will also have a valid home directory.

RTEMS defaults the prefix to /opt/rtems/${version} where ${version} is an RTEMS major version number. The /opt directory is a old Unix top level path for optional data. I recommend you stay from any paths owned by the operating system such as /usr or even /usr/local as it helps updating and upgrading your operating. I create /opt/rtems as root and then make that directory read and write accessible so I do not need to perform RTEMS installs as root. A team environment may have limit write access to provide tighter configuration control and avoid an accidental erasing of the installed tools.

The RTEMS Deployment Tool

The RTEMS Project provides the RTEMS Deployment tool with a set of configurations and packaging options. It is a repository with configuration files for the RSB in a config directory and a means to add and support packaging options. The tool uses the waf build framework to manage the dependencies between the configuration options and packaging input files.

Getting Sources

You need a copy of the RSB you want to use to build your tools and packages with. The RTEMS Deployment tool references the RSB sources you provide. the RSB can be from git, a release tar file or a private copy you maintain.

In this example I will clone the RTEMS RSB and the RTEMS Deployment repositories:

cd somewhere
git clone https://gitlab.rtems.org/rtems/tools/rtems-source-builder.git
git clone https://gitlab.rtems.org/rtems/tools/rtems-deployment.git

Note: If you want to track a release branch enter each of the cloned directories and change branches.

Configuring RTEMS Deployment

Change into the deployment sources and configure with the path to the RSB:

cd rtems-deployment
./waf configure --prefix=/opt/chris/rtems/7 \
       --rsb=../rtems-source-builder

The path to the RSB can be relative or absolute. The --prefix option is where the deployed tools are located.

Note: you will need python3 in your path. This can be a virtual environment.

Configurations

The deployment tool’s config directory contains the current set of configurations. In this example I will detail the AMD configurations.

AMD

The config/amd directory contains:

  • amd-kria-k26.bset
  • amd-kria-k26.ini
  • avnet-microzed.bset
  • avnet-microzed.ini

The build-set (.bset) files define the software stack to build and the kernel configuration (.ini) files customizes the RTEMS kernel.

There are two builds, one for the AMD KRIA K26 module and the over is for the Avnet Microzed. The K26 build-set contains:

#
# AMD Kria K26 (Xilinx Ultrascale+)
#
%{rtems_version}/rtems-aarch64
%define with_rtems_bsp_config config/amd/amd-kria-k26.ini
%{rtems_version}/rtems-kernel
%{rtems_version}/rtems-libbsd-fb14
net/net-services
devel/yaml-cpp
www/civetweb

It builds the:

  1. AARCH64 tools
  2. RTEMS kernel with the config/amd/amd-kria-k26.ini configuration
  3. LibBSD FreeBSD 14
  4. RTEMS Net Services
  5. YAML C++ library
  6. Civetweb Web Server

The kernel configuration inherits the aarch64/zynqmp_apu BSP to make a aarch64/k26 BSP:

[DEFAULT]
RTEMS_POSIX_API = True

#
# KR26 BSP configuration
#
[aarch64/k26]
INHERIT = zynqmp_apu
RTEMS_SMP = True
BSP_XILINX_ZYNQMP_RAM_LENGTH = 0xFFFF0000
ZYNQ_UART_KERNEL_IO_BASE_ADDR = ZYNQ_UART_1_BASE_ADDR

List Build Targets

You can list the build targets with the list target:

./waf list

The left column values can be used as build targets.

Building TAR file

The RTEMS Deployment tool can build one or build targets. To build the AMD targets enter:

./waf --targets=amd/amd-kria-k26,amd/avnet-microzed

Once finished the tar directory will contain two compressed TAR files. The out directory contains RSB log files for the builds. The log file paths mirror the configuration path.

Building RPM Packages

The RTEMS Deployment tool can generate RPM spec files if your host has a working rpmbuild tool. You use the rpmbuild tool to build the RPM file using the generated spec file.

A host packaging system provides useful features:

  1. Installs and uninstalls the files
  2. Verification of the installed files
  3. Ability to add extra versioning information
  4. Ability to query what has been installed

There are weakness in this implementation. Multiple RPM builds for the same install path (--prefix) can overwrite files installed by another RPM. Individual install paths can be used to avoid the problem.

To generate the spec files enter:

./waf rpmspec

To build the RPM enter:

rpmbuild -bb out/amd/amd-kria-k26.spec

What is RTEMS Deployment Doing?

The RTEMS Deployment tool does not display the normal RSB output when building a TAR file. The RSB log option is used to create a build log. The log file is same name as the configuration target you are building with a .txt extension.

For example, running:

./waf --targets=amd/amd-kria-k26,amd/avnet-microzed

Will create a log file of out/amd/amd-kria-k26.txt and out/amd/avnet-microzed.txt. If you tail or watch the log file with less and f you see where the RSB is up to in the build.

RSB Options

You can configure the deployment build with RSB options. Add --rsb-options and then a quoted string with the options. This lets you override some of the defaults in the RSB as if you are running it manually.

RSB Download URL

If you have a restricted network or you want to use a custom set of sources and patches specific the --url option with the RSB. With deployment you can use:

--rsb-options="--url https://ftp.rtems.org/pub/rtems/releases/6/6.1/sources"

To download the sources from the RTEMS 6.1 release.

1 Like