Enabling GPP Platforms

To execute on GPP platforms, new additions or modifications to the OpenCPI framework software may be required. The framework software is highly portable and is supported on a number of platforms and environments. However, it is possible for a new compiler, toolchain, or system libraries to require adjustments to the OpenCPI framework software. Here are a few reasons that may require modifications to framework software:

  • New compilers have new correct warnings that should be addressed.

  • System headers conform better to standards, requiring new correct header inclusion.

  • Some compilers are “dumber” that others, requiring code to be “dumbed down” to avoid language or library features that are not universally supported.

  • Some compilers are stricter than others, requiring code that was previously accepted to be “tightened up” to be strictly compliant and accepted.

These reasons may result in modifications to the OpenCPI framework software, but they should not and cannot make that software stop working on existing supported platforms. Any such modifications should be done with care, and whenever possible, the modifications should be rebuilt and retested on a number of existing supported platforms. Such updates should be submitted in a merge request to OpenCPI.

The process of enabling a GPP platform is based on a source distribution of OpenCPI. A binary/packaged distribution of OpenCPI such as binary RPMs, is not appropriate for enabling a new development host.

Enable a new software platform for OpenCPI requires some experience with make and bash. If you are not familiar with make files and bash scripts, it will be difficult. OpenCPI assumes the availability of bash, make, and python3 on all GPP development hosts.

Enabling OpenCPI Development Targeting New GPP Platforms

GPP (software) platforms are established by creating a new directory under the rcc/platforms/ directory in any OpenCPI project.

The name of the directory (the platform’s name) should be a lower case name that usually includes a OS major version after the name of the OS. In particular, different versions of Linux should be named by their distribution name or organization providing the OS. Examples for software platforms are: rocky8, ubuntu22_04, xilinx24_1_aarch32. The naming concept is that each software platform has binary compatibility within its minor versioning, but not necessarily with major versioning. The currently supported software platforms can be found in the rcc/platforms/ directory of the projects that are part of the OpenCPI source tree. Anyone can add support for new software platforms in their own OpenCPI projects.

The required and optional files in the platform’s directory are defined in the Software Platform Files in the Platform’s Directory topic below, but a discussion of why and how they are used occurs first.

Whether a software platform is the development host itself, or an embedded GPP using cross-development, the tool chain must be established on a development host. For enabling development hosts, there is typically a default tool chain that is installed globally in the system for any development task on that system. For embedded cross-developed platforms, a specific cross-development package must typically be installed using one of several methods described below.

Satisfying the OpenCPI software dependencies for any platform uses two classes of underlying software installations:

  1. Prebuilt, globally-installed software packages that are a (usually optional) standard part of an operating system installation.

  2. Externally sourced software packages that require a separate combination of downloading, building and installation.

We use the term standard packaged software to indicate the first category. E.g, a package of development tools is commonly a standard installation option on many systems. Since they are standard packages for a given operating system installation, they are prebuilt and installed globally on the (usually a development) system. Installation of such software is usually accomplished using commands like yum or apt.

The second category is essentially ad hoc extra required software that must be installed using specific scripts unique to that software. We use the term prerequisites for such software, and expect individual scripts to be written to download/build/install them. Software packages required by OpenCPI at runtime are normally prerequisites since they must be cross-compiled for all embedded platforms, whereas those required only for development may be supplied in either of the two categories.

So for any given platform, OpenCPI requires a combination of standard packaged software and prerequisite software.

OpenCPI uses the following process steps when building itself for a software platform, based on the open source tree from gitlab.com. Enabling all these steps is described below.

  1. Install the standard software packages required for OpenCPI from the appropriate network software package repository (usually associated with the Linux distribution), e.g. development tools for the development host. 1

  2. Download and build any platform-specific prerequisite software packages, that are not available as standard packaged software. 2

  3. Download and build the standard (always or frequently used) OpenCPI-specified prerequisite software packages.

  4. Build the OpenCPI framework libraries and executables from source code.

  5. Build all the software assets in the built-in projects that are part of OpenCPI, in the same gitlab repository (RCC workers and ACI applications).

  6. Run a number of tests to verify OpenCPI operation (software only).

For a fully enabled/supported development host, the above steps are all done in the single master installation script called:

$ ./scripts/install-opencpi.sh

For enabled/supported embedded software platforms (and all other types of platforms), the above steps (except testing, step #6) are done with ocpiadmin tool for platforms that are not development hosts:

Installing an OpenCPI Platform

ocpiadmin install platform

Prepare the OpenCPI installation for using the specified RCC or HDL platform.

Usage:

$ ocpiadmin install platform [OPTIONS] Platform

Arguments:

  • Platform: [required]

Options:

  • --install-target / --no-install-target: Whether to also install the platform’s HDL target. [default: install-target]

  • -w, --workers: Whether to build workers for the installation target.

  • -t, --tests: Whether to build unit tests for the installation target.

  • -a, --assemblies: Whether to build assemblies for the installation target.

  • -r, --artifacts-only: Whether to clean intermediate build files.

  • -s, --streamline-build: Whether to skip checkpoints when building assemblies.

  • -o, --optimize: For RCC platforms only. Install platform and workers with optimization enabled.

  • -j, --n-jobs INTEGER: Max number of parallel builds [default: 1]

  • -p, --package-id TEXT: Package ID of platform/target to install.

  • -u, --project-url TEXT: URL to the platform/target’s project.

  • -g, --git-revision TEXT: Git revision to checkout before installation.

  • --report-format [junit]: Format of report(s). [default: junit]

  • --report-path FILE: Path of file to write report(s) to.

  • --builder [make]: Specify the Builder to use to run the asset(s). [default: make]

  • --help: Show this message and exit.

Testing embedded platforms is not part of the installation since it usually requires additional hardware setup and configuration.

These above steps, and how to enable them for a software platform, are described in detail in the following sections. A summary of the files required in a platform’s directory to enable the above steps is:

  1. A software platform definition file, named <platform>.mk, which sets variables that describe the platform. Between 3 and 20 variables might be required.

  2. For development hosts only, a script to check that the currently running system is in fact the given software platform, e.g. answering the question: is this system running <platform>? The script is typically 5-10 lines of shell script code, and is called <platform>-check.sh.

  3. If needed, a script to install various standard packaged software from software package repositories to support OpenCPI for this platform, called <platform>-packages.sh.

  4. If platform-specific prerequisite packages are indicated in the software platform definition file, then there should be a prerequisite script for each one, named install-<prerequisite>.sh.

The OpenCPI Build Process for Software Platforms

The OpenCPI build process is designed to support a variety of platforms all built in the same source tree. I.e. all the built results for all platforms coexist in a directory structure, in per-platform directories. This allows:

  • Multiple development hosts to share the same file system and same copy of the source tree

  • Multiple cross-compiled/embedded platforms all built in the same source tree, even when cross-compiled using different development hosts.

  • Multiple disparate runtime systems to share the same OpenCPI installation via network mounts.

This structure allows for rapid and productive development, debugging and testing across a range of platforms simultaneously. The process of building for a given platform thus can coexist with others and can mostly proceed in parallel, independently, from one or more development hosts.

Self-identify the Development Platforms

When building for development platforms, the first step in the build process is to decide which platform we are actually running on and where its directory of platform-specific files is. After this, the various scripts and tools associated with that platform are used.

Typing ./scripts/install-opencpi.sh (or individual scripts called by that script) at the top level of the OpenCPI source tree does this self-identification step almost immediately. The algorithm for this is:

  • For each project indicated in the project registry and each project indicated in the OCPI_PROJECT_PATH environment variable, look for software platforms defined in the rcc/platforms directory, and invoke the <platform>-check.sh script found there. If that script succeeds, that platform and its directory are now used as the platform we are running on.

The exact definition and operation of this script, and examples, are described in the Platform Self-Identification/Check Script for Development Platforms topic. Even when targeting cross-development platforms, the development host platform must still be identifiable this way. When building OpenCPI for cross-developed platforms, the target platform name is specified explicitly, but the same project search algorithm is used to find a rcc/platform/<platform> directory for the specified platform. No <platform>-check.sh script is needed for cross-developed platforms.

Install Standard Packaged Software from the OS’s Package Repository

The tools required to support OpenCPI development on a development host are usually obtained using standard package management software (e.g. yum or dnf on Rocky) and the OS’s repositories accessible on the internet. Different Linux distributions use different repositories, and different commands, to retrieve and install software packages from those repositories. If a platform requires any such packages to be installed, there must be a script file <platform>-packages.sh in the platform’s directory.

This <platform>-packages.sh script is run after self-identification to install any standard packaged software needed to build the OpenCPI software:

  • prerequisite packages

  • the OpenCPI framework

  • the built-in projects in the OpenCPI gitlab repo.

The standard software package repository used may in fact be local on the system or on the local network rather than being internet-based.

These standard packages are generally globally installed on the system, and not in any “sand box” only for use by OpenCPI. Thus they are considered default installations of standard software for the platform. If a software package should not be globally installed (not be seen or used by other users or other software), we consider that a prerequisite package, which requires its own installation script, described next.

Thus if a package requires non-standard/customized patches in order to be used for OpenCPI, it must be installed as a prerequisite, not as standard packaged software.

Embedded and cross-developed platforms do not usually install software from a software package repository into a global location on the system, but if that is desired or required, such platforms may also have a <platform>-packages.sh script.

Install Prerequisite Software Packages in the OpenCPI Sand Box

After the installation of pre-built standard packaged software from OS repositories is done (if there are any), the next step is to build and install prerequisite software packages in a directory solely used by OpenCPI (and thus not seen or used by other users or software). Each prerequisite software package has its own installation script, as defined in the Prerequisite Installation Script topic.

The term prerequisite here implies a software package that is independently downloaded, usually built-from-source, and installed in the OpenCPI sand box (in the source tree). This is in contrast to the previously discussed packages, installed prebuilt from software package repositories and installed globally, visible and usable by all users and unrelated software.

There are two types of prerequisites, each installed using the same type of script:

  1. Platform-specific scripts that support the development requirements of OpenCPI (e.g. compilers, or other required utilities) for a particular platform.

  2. OpenCPI-standard prerequisites required by some or all platforms, both development and cross-compiled.

The first type requires installation scripts be supplied in the platform’s directory, while the second type has installation scripts that are part of OpenCPI. A platform indicates, in its platform definition file (<platform>.mk) whether it has any such platform-specific prerequisites, and if so, its scripts are run before building any of the second type of prerequisites. This allows the first type (perhaps cross compilers) to enable building the second type (the standard required prerequisites for OpenCPI). All prerequisite installation scripts have the name:

install-<prerequisite>.sh

Each such script can build its package in whatever way is needed, which can vary widely, but can rely on previously installed packages.

The results of this step appear in the prerequisites directory of the OpenCPI source installation.

Build the OpenCPI Framework Libraries and Executables

After the standard packaged software is installed, and the platform-specific and OpenCPI common prerequisite packages are built and installed, the OpenCPI framework can be built. This is done as part of the install-opencpi.sh script (for development host platforms) or the ocpiadmin install platform <platform> operation (for embedded platforms).

Building the framework depends on a tool chain declared in the platform definition file, as well as any platform-specific (if any) and OpenCPI common prerequisites.

The results of this step are made available in the exports/ directory of the source tree, in a subdirectory whose name is the platform. Executables are in exports/<platform>/bin/, and libraries are in exports/<platform>/lib.

Build the Assets in the Built-in Projects in the OpenCPI git Repository

The final step of building OpenCPI is building all the software assets in the projects that are present in the OpenCPI source tree (from its gitlab repository). The built-in projects are currently core, platform, assets, tutorial and inactive. This occurs as the last part of the install‑opencpi.sh script or ocpiadmin install platform <platform> operation.

This builds all software workers and ACI applications in these projects. This includes performing the equivalent ocpidev build command in each project.

When a new software platform is defined correctly, this step represents a successful software platform definition, for building.

Test the OpenCPI Installation for a Software Platform

The last step in install-opencpi.sh is running some tests of the development software platform. This also tests aspects of OpenCPI that are not all related to software platforms, but if it succeeds completely, it is a good indication of success. This script includes some asset unit tests in the built-in projects.

For embedded platforms, the analogous test function is executed on the embedded platform after it has been prepared for OpenCPI (using ocpitest), which normally occurs after preparing a bootable media (e.g. SD card) for the platform. The ocpiadmin install platform <platform> operation skips the testing phase.

Software Platform Files in the Platform’s Directory

Defining a software platform for OpenCPI involves 4 types of files in its directory, rcc/platforms/<platform>, in some project:

  • The platform definition file <platform>.mk

  • The platform self identification file for development systems only: <platform>‑check.sh

  • The optional package installation file: <platform>-packages.sh

  • The optional platform exports file: <platform>.exports

  • Optional platform-specific prerequisite installation scripts: install‑<prerequisite>.sh

Each type of file is described in the following sections.

Platform Definition File: <platform>.mk

This required file is processed by make, and thus uses make syntax. It contains a set of variable assignments to override default values as required by the platform. The list of valid variables, their default values, and the descriptions, are in the file:

tools/include/platform-defaults.mk

Three variables are required, and the rest are only used to override default values. All variables are in “camel case”, with the prefix Ocpi. The required variables are:

OcpiPlatformOs

the operating system name in lower case, e.g. linux or macos.

OcpiPlatformOsVersion

the major version, usually a short name with a numeric major version. For Linux, it is a prefix before the major version, indicating the distribution, e.g. r for Rocky, u for Ubuntu, m for Mint etc.

OcpiPlatformArch

the CPU architecture, usually as returned by the uname -m command, e.g. x86_64.

Two other important variables are:

OcpiPlatformPrerequisites

a list of required software prerequisite names for platform-specific prerequisite packages for which the platform will supply installation scripts.

OcpiCrossCompile

an absolute pathname and prefix of the compilation toolchain tools for the platform, assuming packages and prerequisites are installed.

The presence of the OcpiCrossCompile variable setting indicates a cross-compiled platform. If the cross compiler used is in fact a declared prerequisite for the platform, this make variable definition indicates where its executables are:

$(OCPI_PREREQUISITES_DIR)/<prerequisite>/$(OCPI_TOOL_PLATFORM)/bin

When this <platform>.mk file is processed, it is checked for variable assignments that are not in the list of valid variables, which results in a warning if variables assigned are not in the list of valid variables. All the default values are as needed for Rocky9, and thus all assignments (except for the three required ones) are only needed to override those defaults. All variables are initially defined with a default value as “simply expanded” or “immediately expanded” make variables using the := assignment syntax.

A simple example of this file is the current definition for Rocky9. Since the defaults defined in platform-defaults.mk are basically for this platform, there are not many variables:

OcpiPlatformOs:=linux
OcpiPlatformOsVersion:=r9
OcpiPlatformArch:=x86_64

For the cross-compiled Xilinx Zynq-7000 Linux platform (xilinx24_1_aarch64), from the version 24_1 (2024, the 1st quarter) the platform has a different compiler, and relies on the compiler that is embedded in the Xilinx tools package already installed separately. Its definition file looks like this (with some abbreviations):

include $(OCPI_CDK_DIR)/include/xilinx/xilinx-rcc-platform-definition.mk

OcpiCXXFlags+="-Wno-type-limits"
OcpiKernelDir=$(mkfile_dir)/gen/kernel-artifacts/aarch64/headers
OcpiPlatformOs:=linux
OcpiPlatformOsVersion:=24_1
OcpiPlatformArch:=aarch64
OcpiRequiredCXXFlags:=$(OcpiRequiredCXXFlags) -Wno-psabi

There is no package or prerequisite installation script for this platform since its tool chain is available as a side effect of a separate, global, installation of Xilinx FPGA tools.

This file should not introduce or set any make variables not defined in platform-defaults.mk. If temporary variables are required, they should use the make foreach function if possible (see the rocky9.mk file for an example).

Platform Self-Identification/Check Script for Development Platforms

This script is named <platform>-check.sh and is required only for development platforms, and is executed with the bash shell. It returns success (an exit status of zero) if the running system is indeed this platform. If it is does not determine that the running system is this platform, it should return a non-zero exit status.

Normally each Linux distribution or other operating system has some files that indicate its native distribution or release type, as well as which major version is running. So the task of this script is to check for those files as well as the major version number.

These scripts are usually quite simple, and several are listed here verbatim as examples:

For Rocky Linux platforms, where the /etc/rocky-release file contains something like:

Rocky Linux release 9.5 (Blue Onyx)

the entire script file can be:

[ ! -r /etc/os-release ] && exit 1
source /etc/os-release
[[ "${ID}" == "rocky" && "${VERSION_ID}" == "9"* ]] && exit 0 || exit 1

Since all scripts are invoked explicitly using the bash shell, no execute permission or initial #!/bin/bash line is necessary. OpenCPI has an explicit requirement for the bash shell on all development platforms.

Platform Package Installation Script

The <platform>-packages.sh script, invoked using bash, is required for platforms that use or require standard packaged software, prebuilt and globally installed from a (usually network-based) software package repository. It has two functions:

  • install the required software packages from the repository

—or—

  • list the required software packages on standard output

When this script is called with no arguments, it simply uses the appropriate commands to install the required software. Since these packages are installed globally, the installation commands usually require administrative permissions (e.g. using sudo in the script).

If the single argument to this script is list, then the second, listing function is requested. In the list mode, it must list on stdout the names of required packages on 4 lines:

  1. The packages necessary for OpenCPI runtime packages/RPMs

  2. The packages necessary for OpenCPI development packages/RPMs

  3. The packages necessary for an OpenCPI source environment (e.g. for building the framework) beyond what is needed for #1 and #2.

  4. The packages that are for development (#2), but which must be installed in a second phase after those on the second line.

In list mode, packages are package names suitable for RPM creation. Note that for RPMs, if a required package is not the same architecture as the platform (e.g. when a 32-bit package is required on a 64-bit platform), a pathname of a file supplied by the package must be listed rather than the name of the package.

If the first argument to this script is yumlist, the same output is required except that it is not limited by the RPM constraint above, and only lists packages to be installed.

The existing scripts for Rocky, Ubuntu, or Mint platforms are good examples. In general the script is roughly:

RPKGS="a b c d" # required packages for runtime
DPKGS="a1 b2 c3 d4" # required packages for development
OPKGS="a5 b6 c7 d8" # required packages for framework development
EPKGS="a9 b10 c11 d12" # Second phase development packages
[ "$1" = list ] && echo $RPKGS && echo $DPKGS && echo $OPKGS &&
                   echo $EPKGS&& exit 0
<install-command> $RPKGS $DPKGS $OPKGS
<install-command> $EPKGS

For Rocky and RedHat systems, the <install-command> is:

$ sudo yum -y install

On Debian or Ubuntu or Mint Linux systems, the <install-command> is:

$ sudo apt install -y

Any platform-specific software required for OpenCPI must either be installed by this script (for globally installed prebuilt packages from a repository), or using what OpenCPI calls prerequisite installations, which are described next.

Since these scripts are invoked explicitly using the bash shell, no execute permission or initial #!/bin/bash line is necessary (but not precluded). OpenCPI has an explicit requirement for the bash shell on all development platforms.

Platform Exports File

This optional file, <platform>.exports, specifies what files in the platform’s directory should be exported and made visible to “users” of the platform. Its syntax is a series of lines specifying files or directories to be exported under three different conditions, indicated by a prefix character at the start of the line, with + for development files, = for runtime files, and @ for deployment files (e.g. bootable media, SD card). Thus each (non-comment - using #, non blank) line contains three things: a prefix, a source-tree location (LHS), and an exported location (RHS):

[+=@] <source-location> <exported-location>

Each line is similar to a “cp” command.

When a file to be exported is in the platform’s own directory, the literal string <platform-dir> in the LHS is replaced with the actual platform’s directory pathname. The LHS string can use wildcards (e.g. <platform_dir>/sub.*).

The second string (RHS) on each line is optional. If it is not present, the file or directory indicated in the first string (LHS) is exported at the top level of the platform’s exports.

The RHS string is the location where the LHS file or directory will be exported. A trailing slash on the RHS indicates a directory where the LHS will be placed, which will automatically be created as required.

As a special case, when the prefix is @ (for deployment), the RHS indicates a location on the bootable SD card (or equivalent). The default location is the root of the SD card, which is equivalent to a slash. On an SD card, the entire OpenCPI runtime package is installed under the opencpi/ directory.

Much like HDL platforms, and component libraries, the files that are indicated for export are all automatically exported using symbolic links in a lib/ subdirectory of the platform’s directory.

This local lib/ subdirectory is exported from the project, in the exports/rcc/platforms directory of the project.

Finally, depending on the prefix character in the file (+, =, or @), these files are exported by the framework as a whole for the different ways that OpenCPI is packaged (development package, runtime package, deployment/SD-card packages).

Note that the platform definition file, the check file, and the exports file itself are automatically exported and do not need to be mentioned in the exports file.

Prerequisite Installation Script

If the OcpiPlatformPrerequisites variable is set (not empty) in the platform definition file, an installation script for each listed prerequisite is required to be present in the platform’s directory, with the name install-<prerequisite>.sh. E.g., if the variable assignment is:

OcpiPlatformPrerequisites=preqx preqy preqz

then scripts named:

install-preqx.sh install-preqy.sh install-preqz.sh

must all be present.

Prerequisites are installed in an OpenCPI installation directory so that they do not interfere with other global software installations and are thus considered part of the OpenCPI installation (or “sand box”). Both runtime library prerequisites (for any platform) and tool prerequisites (for executing on development platforms) are installed there.

  • This directory’s default location in the prerequisites/ subdirectory of the source tree. This may be overridden by setting the OCPI_PREREQUISITES_INSTALL_DIR if the default is unacceptable.

  • In an RPM OpenCPI distribution (prebuilt, installed globally) it is /opt/opencpi/prerequisites.

In a source code installation, prerequisites are built and installed in the source tree itself, in the respective prerequisites-build/ and prerequisites/ subdirectories. Thus these packages do not interfere with other global software installations or other OpenCPI installations/versions. Both runtime library prerequisites and tool prerequisites are typically installed here.

When a prerequisite has libraries, the libraries are automatically installed in the directory for framework libraries, e.g. exports/<platform>/lib in a source build or /opt/opencpi/cdk/<platform>/lib in an RPM installation.

This script should follow the pattern of other install scripts in the build/prerequisites/ directory of the OpenCPI framework (e.g. install-gmp.sh), in particular:

  • Ensure that the OCPI_CDK_DIR environment variable is set.

  • Source the $OCPI_CDK_DIR/scripts/setup-prerequisite.sh script with appropriate arguments.

  • Install any resulting platform-independent header files in $OcpiInstallDir.

  • Install platform-specific files in the include, lib and bin subdirectories of: $OcpiInstallExecDir.

  • Build both dynamic and static versions of runtime libraries, and build the static libraries with PIC options enabled.

  • If cross-building, use the $OcpiCrossHost variable as the prefix for tool executables (e.g. as the --host option to ../configure)

The $OCPI_CDK_DIR/scripts/setup-prerequisite.sh script, supplied by OpenCPI, which is sourced, takes these arguments:

  1. The target platform (the platform on which execution takes place). This is passed in from the first argument of the install script, e.g. "$1" (quoted to allow empty).

  2. The name of the prerequisite, e.g. gmp.

  3. A short “pretty” description string, e.g. "Extended Precision Library".

  4. The URL (or absolute pathname) to download the file from, without the filename, e.g.: https://ftp.gnu.org/gnu/gmpIf the URL ends in .git, it will be cloned rather than downloaded and unpacked.

  5. The downloaded file name (if a downloaded file), e.g. gmp-6.1.2.tar.xz, or, if cloning a git repository, the tag or branch to check out.

  6. The top-level directory implicitly created when the download file is unpacked, e.g.: gmp-6.1.2 or the git repository top level directory. Use a single period (.) if the download is a single file, with no implied directory.

  7. An indication as to whether the prerequisite should be cross-compiled, or only used on development hosts. A value of 1 indicates runtime and cross compiled for non-development platforms. 0 means only build for development platforms since it is not needed at runtime.

This setup script performs downloading (or git cloning), caching downloads, creating the necessary directories, accessing the tool chain for the platform, and defining convenience functions and variables for use later in the script.

After the setup script is sourced, the environment is setup as follows:

  • the current working directory is a newly created platform-specific build subdirectory created under the directory created by the download/unpack, or git clone

  • the OcpiInstallDir and OcpiInstallExecDir variables are set to where the results of the build should be installed

  • the relative_link function is defined to create appropriate relative symbolic links from the installation directory to this build directory.

  • the shell option to terminate on any error (set -e) is set.

  • variables for explicit (non-autotools) compilation are set compatibly for cross compilation: CC, CXX, LD, AR.

  • the OcpiCrossHost variable is set appropriately for the autotools --host option.

  • the cross-compilation tools are in the execution PATH environment variable.

Note that the current working directory is a new directory created for the platform for which the prerequisite is being built. This enables different builds for different platforms to avoid conflict with each other. However it assumes that the build commands that are executed after sourcing the setup-prerequisite.sh script do not modify files in other parent directories. If the prerequisite’s compilation scheme does not allow for build results to be put in a separate “build” directory, then a copy of the sources must be made into this newly created platform-specific directory. An example of this is in the install-gpsd.sh script in the source tree.

At this point, the prerequisite installation script can perform an appropriate build in this directory. When the build is complete, the results must be installed (usually using relative_link) in the directories: $OcpiInstallDir and $OcpiInstallExecDir. Depending on how the prerequisite package is natively built, some knowledge of its own build system may be required, such as autotools or scons or cmake. Normally the last few lines of the script are similar to the recommended source installation for the package.

This installation happens one of two ways. If the build uses the typical autotools paradigm of:

../configure; make; make install

then the --prefix and --exec-prefix arguments are provided to the configure script as, e.g.

../configure
  --prefix=$OcpiInstallDir
  --exec-prefix=$OcpiInstallExecDir

This will cause the resulting files to be installed in the correct locations (e.g. $OcpiInstallDir/include for portable headers, and $OcpiInstallExecDir/(lib|bin|include) for platform-specific files).

An example script for a prerequisite needed only on most development platforms, is the patchelf tool. The entire install script is:

version=0.9
dir=patchelf-$version
[ -z "$OCPI_CDK_DIR" ] &&
   echo Environment variable OCPI_CDK_DIR not set && exit 1
source  $OCPI_CDK_DIR/scripts/setup-prerequisite.sh \
        "$1" \
        patchelf \
        "ELF file patching utility" \
        http://nixos.org/releases/patchelf/$dir \
        $dir.tar.gz \
        $dir \
        0
../configure --prefix=$OcpiInstallDir \
             --exec-prefix=$OcpiInstallExecDir \
             CFLAGS=-g CXXFLAGS=-g
make && make install

For prerequisite packages that are not set up for autotools building, the results of the build can be simply installed using the relative_link function which operates as a smarter symbolic link command analogous to the ln -s command. Here is an excerpt from a prerequisite installation where the software package being installed consists of a single source file:

[ -z "$OCPI_CDK_DIR" ] && echo Environment variable OCPI_CDK_DIR not set && exit 1
source $OCPI_CDK_DIR/scripts/setup-prerequisite.sh \
       "$1" \
       inode64 \
       "fix for 32 bit binaries running on 64-bit file systems" \
       https://www.tcm.phy.cam.ac.uk/sw \
       inode64.c \
       . \
       0
...
gcc -c -fPIC -m32 ../inode64.c
ld -shared -melf_i386 -o inode64.so inode64.o
relative_link inode64.so $OcpiInstallExecDir/lib

For runtime prerequisite packages that need to be cross compiled, the OcpiCrossHost variable is used in the ../configure command, e.g.:

../configure --prefix=$OcpiInstallDir --exec-prefix=$OcpiInstallExecDir\
             ${OcpiCrossHost:+--host=$OcpiCrossHost}

With prerequisites that are not set up for autotools, the compilation commands can be used directly, e.g.:

$CXX -c *.c; $AR -rs foo.a *.o

Note that the variables set or defaulted in the platform definition file (i.e. <platform>.mk) are available to be used here.

The Makefile for a Software Platform

A software platform may have a Makefile in its directory if it needs to perform any processing steps to create the necessary files prior to building OpenCPI. This Makefile is automatically used (with the default make goal/target), prior to building OpenCPI itself with the build-opencpi.sh script that is used by the install-opencpi.sh script and the ocpiadmin install platform command.

This Makefile is used when files need to be brought into the directory from external sources or downloads. An example is when the files needed have license constraints or are based on installing licensed software and can thus not simply be copied into the public repository.

Summary for Enabling Development for a New GPP Platform

  • Create the platform’s directory in a project’s rcc/platforms/ directory.

  • Create the platform definition file.

  • For development hosts, create the <platform>-check.sh script.

  • If needed, create the <platform>-packages.sh script.

  • If needed, create the package-specific prerequisite installation scripts.

  • If needed, create a local Makefile for the platform.

  • Build the OpenCPI prerequisites to ensure all the scripts are functional.

  • Build the OpenCPI framework and make adjustments to the code for issues that arise.

  • Successfully run ./install-opencpi.sh on the development host.

  • Successfully run ocpiadmin install platform for cross-developed platforms.

  • Successfully run ocpitest on embedded hosts.

Enabling Execution for GPP Platforms

The OpenCPI framework libraries and command-line tools are built using the appropriate compiler as installed above. Once the development host has been enabled, and the OpenCPI core and example components have been built, a few additional steps are required to enable execution on the platform.

Several OpenCPI runtime libraries have aspects that use conditional compilation depending on the system or CPU being targeted. The current OpenCPI core libraries have significant Linux dependencies and in several files there is conditional code between Linux and MacOS (such as low level networking details). There are a few areas that have conditional code depending on the CPU being used, such as realtime high resolution timing registers in the CPU. These customizations are not well defined. For new CPU architectures and new operating systems not based on Linux, the code must be examined for these issues, which will typically cause compilation errors.

Setting up a development system for execution is nearly automatic once the build environment is set up and any required code changes in the OpenCPI runtime libraries. For execution on development systems, using the normal installation steps described in the OpenCPI Installation Guide, are sufficient (i.e. using the source cdk/opencpi‑setup.sh -s script).

Loading the OpenCPI kernel driver (via the ocpidriver command) is necessary when accessing other platforms via the system bus. If the GPP platform has no such bus/fabric, or there are no OpenCPI-capable cards plugged in, the kernel driver is not necessary.

For embedded systems, the setup is more customized.

Creating a Deployment Package (Bootable Image or SD card) for an Embedded Platform

A “runtime” package for an embedded platform is a set of files which can be installed on a network file server (usually the development host), which can be accessed with the embedded system acting as a file client. The next step to achieving runtime is to install some appropriate files on the embedded system itself. We call this set of files a “deployment package”.

A deployment package is created for either an embedded software platform by itself, or a combination of an embedded software platform and an HDL platform. This combination is common on SoCs like Zynq and CycloneV.

The exports file defined above in the Platform Exports File topic specifies the files that will be placed on the SD card for this software platform. When the standard operation to create SD cards is run according to the installation guide (using the ocpiadmin deploy platform operation), the following steps are taken:

  1. Copy the standard OpenCPI runtime files for the platform to the SD Card

  2. Copy the files designated with @ in the software platform exports file

  3. Copy the files designated with @ in the HDL platform’s exports file.

This combination of exports from the two platforms creates the content of the bootable SD card. Notice that the HDL platform is exported last, and thus can specify files that override files copied by the software platform.

Deployment packages are thus created by combining the appropriate exports from the software and HDL platforms to create the necessary files for the “system” that combines that software platform with the HDL platform.

The files on the bootable image can fall into two categories:

  • The minimum set of files necessary to run OpenCPI assuming it has access to a runtime package on a network server.

  • The additional files necessary to run OpenCPI standalone, i.e. with no network, where the runtime files are on the card.

Thus for platform exports, the + lines indicate platform-specific exports for the development package (not used at runtime, only on development host), = indicates platform-specific exports for the runtime package (used on development host as server or directly on the SD card), and @ indicates platform-specific exports for a deployment package (SD card only).

First, in the normal course of building OpenCPI for the targeted platform, the software platform would be already be built by running:

$ ocpiadmin install platform xilinx24_1_aarch32

and then the built-in projects, including those containing the HDL platform, would be built with:

$ ocpiadmin install platform zed

So then the particular command to create the deployment package would simply be:

$ ocpiadmin deploy platform xilinx24_1_aarch32 zed

When ocpiadmin deploy platform is run, the bootable media directory tree is placed in this directory in the source tree:

cdk/<hdl-platform>/sdcard-<sw-platform>/

This directory can then be copied to an SD card for use on the platform.

1

Software package repositories are sometimes captured locally when internet access is not always available. Some standard software packages are individually captured/downloaded so they can be (re)installed offline.

2

Similarly, prerequisite software is sometimes downloaded and stored locally/offline and the “download” step simply uses the locally available downloads.