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:
- AARCH64 tools
- RTEMS kernel with the
config/amd/amd-kria-k26.ini
configuration - LibBSD FreeBSD 14
- RTEMS Net Services
- YAML C++ library
- 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:
- Installs and uninstalls the files
- Verification of the installed files
- Ability to add extra versioning information
- 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.