Developing Applications in OpenCPI Projects

Applications are typically XML files. They may also be C++ or Python main programs using the ACI. All types of applications rely on the existence of existing artifacts found via OCPI_LIBRARY_PATH.

Applications may also be created as part of an OpenCPI project containing other OpenCPI assets such as components, workers, primitive libraries, etc.

In OpenCPI a project represents a work area in which a variety of assets are created and developed. Projects can contain all types of OpenCPI assets that are described in this document or in others. A project can contain:

• Component libraries with specs and workers (described in the OpenCPI Component Development Guide)

• Applications whether simple XML or using the ACI (described here).

• HDL primitives and assemblies (described in the OpenCPI HDL Development Guide)

• HDL devices, cards, slots (described in the OpenCPI HDL Development Guide)

• Platform support assets (described in the OpenCPI Platform Development Guide)

A project uses a standardized directory structure that holds the various OpenCPI assets in source code form, along with other files that describe how they are built. The project structure provides a means to co-develop a collection of assets which may have a logical relationship or be created for a specific overall application. Projects may depend on other projects when assets from other projects are needed.

All the assets in a project have a package ID and they all normally share a project-level package prefix.

When an OpenCPI application is developed in a project, an IDE or the ocpidev command line tool is used to manage the project and the assets inside it. Even if the project contains only applications, there are advantages to putting applications into OpenCPI projects, especially during development and especially for ACI-based applications. The ocpidev tool is described next. Discussing any IDE for this purpose is out of scope for this document.

Projects are for development. When an OpenCPI application is deployed on a runtime-only non-development system, projects are not used. Deploying applications and the various files they depend on (e.g. OAS files, ACI executables, artifacts, ocpirun), is described in the Deploying Applications in a Runtime Environment topic.

The ocpidev Tool as Used for OpenCPI Applications in Projects

For pure application users (that are not developing other asset types), the small necessary subset of ocpidev tool’s functionality is described here.

Creating a Project

ocpidev create project

Create an OpenCPI Project.

Usage:

$ ocpidev create project [OPTIONS] NAME

Arguments:

• NAME: [required]

Options:

• --register / --no-register: [default: no-register]

• -D, --depend TEXT: Package-ID of project to depend on. May be used more than once.

• --package-id TEXT: The package ID. Defaults to <package_prefix>.<package_name>

• --package-prefix TEXT: The package prefix. [default: local]

• --package-name TEXT: The package name. Defaults to <name>.

• --xml-include TEXT: Directory to search for XML include files. May be used more than once.

• --include-dir TEXT: Directory to search for include files. May be used more than once.

• --primitive-library TEXT: Primitive library asset depends on. May be used more than once.

• --component-library TEXT: Component library asset depends on. May be used more than once.

• --exclude-platform Platform: Do not allow building asset for specified platform. May be used more than once.

• --only-platform Platform: Only allow building asset for specified platform. May be used more than once.

• --exclude-target HDL Target: Do not allow building asset for specified HDL target. May be used more than once.

• --only-target HDL Target: Only allow building asset for specified HDL target. May be used more than once.

• --help: Show this message and exit.

Deleting a Project

ocpidev delete project

Delete an OpenCPI Project.

Usage:

$ ocpidev delete project [OPTIONS] [Project]

Arguments:

• [Project]

Options:

• -f, --force

• --help: Show this message and exit.

When using projects only for applications, only two types of assets are created in the project: applications and HDL assemblies.

Applications in Projects

Applications in projects live in the applications/ subdirectory of the project and are either XML applications, based on an OAS XML file, or ACI-based C++ programs. XML applications can simply be OAS files in the applications/ subdirectory, or be in a directory of their own, also under applications/. ACI-based applications are always in their own directory. Applications are created in projects by executing this command in a project’s directory:

Create an Application

ocpidev create application

Create an OpenCPI Application.

Usage:

$ ocpidev create application [OPTIONS] NAME

Arguments:

• NAME: [required]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• --xml-dir-app: Create the application as an XML file.

• -X, --xml-app: Specify that the application has its own directory that will contain only an an XML file.

• --help: Show this message and exit.

This command is used to create any of 3 types of application:

• A single OAS XML file, <name>.xml, in the applications/ directory (using the --xml-app option)

• An application in its own directory under applications/, with the OAS XML file created there (using the --xml-dir-app option)

• An ACI application in its own directory under applications/, with the OAS XML file created there, and a C++ source file <name>.cc, also created there.

Placing an application in its own directory allows other related files (e.g. test data, or other source files) to be in the same place.

The applications.xml file in the top level applications/ directory can specify some options that apply to all the applications. If only a subset of the applications should be built or executed, or if they must be built or executed in a particular order, the Applications attribute in that file may contain a list of the applications to be used (built or run) and the order in which they are built and/or used, e.g.:

<applications Applications='myapp1 myapp3'/>

This would only build and run myapp1 and myapp3, even if myapp2 was also present.

Even when an application is excluded from the Applications attribute, it is still possible to manually enter its directory and build or run there. To delete applications, the following command is used:

Deleting an Application

ocpidev delete application

Delete an OpenCPI Application.

Usage:

$ ocpidev delete application [OPTIONS] [Application]

Arguments:

• [Application]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• -f, --force

• --help: Show this message and exit.

When the ocpidev build or ocpidev run command is issued in a project’s directory, all applications are built or run, subject to the Applications attribute if set in the applications.xml file.

Building Applications in Projects

Building XML-only applications (not ACI-based applications) does nothing. ACI-based applications are built in their own directories using the ocpidev build command. From anywhere within a project’s directory, a specific application can be built using the command:

Build an Application

ocpidev build application

Build an OpenCPI ACI Application.

Usage:

$ ocpidev build application [OPTIONS] [Application]

Arguments:

• [Application]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• --rcc-platform RCC Platform: RCC Platform(s) to apply the command for.

• --doc-only: Only build docs.

• --no-doc: Do not build docs.

• --artifacts-only: Clean up intermediate build files.

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

Tip

When building from within an application’s directory itself, you can simply use:

$ ocpidev build

Tip

To build all applications in a project, you can issue the following command from anywhere within the project’s directory:

ocpidev build applications

Build all OpenCPI Applications in a Project or Library.

Usage:

$ ocpidev build applications [OPTIONS] [Application]

Arguments:

• [Application]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• --rcc-platform RCC Platform: RCC Platform(s) to apply the command for.

• --doc-only: Only build docs.

• --no-doc: Do not build docs.

• --artifacts-only: Clean up intermediate build files.

• -j, --n-jobs INTEGER RANGE: The max number of parallel jobs to allow. [default: 1; 1<=x<=48]

• --accumulate-errors: Do not stop builds after a failure.

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

Note

With no target platform specified, the executable is built to run on the development system itself. To build for other software platforms, you can use the --rcc-platform option (multiple times if desired).

E.g., for the ZedBoard embedded platform, the software platform name for the embedded Linux is something like xilinx24_1_aarch32. Thus to build an ACI program for that system would be:

$ ocpidev build --rcc-platform xilinx24_1_aarch32

All executables are created in subdirectories named target-<platform>, so executables for multiple different platforms can coexist.

Application XML Files In Projects

At runtime, an OAS XML file described above in the section on OAS XML Files is used to execute the application, whether in a development environment or a pure runtime environment (with no projects and no ocpidev). The OAS in an application’s directory in a project may have additional attributes that specify options for how the application is built, run, and cleaned in the project (development) environment using ocpidev.

These attributes are ignored if the application is executed outside the development/project environment (i.e. not using ocpidev). They specify:

• Additional source files to compile for an ACI application

• Additional collocated executables to build along with the application

• Additional secondary source files to compile with the ACI application

• Prerequisite libraries required by the ACI application

• Options for executing the application in a project environment

For ACI applications, the actual name of the OAS XML file used at runtime is determined in the C++ source code. In fact, the OAS can be a literal or constructed string in the C++ source with no OAS file used at all for execution. The ocpidev-related attributes listed below may be in the OAS file if it exists (it must exist for an XML-based application created using the --xml-dir-app option). In some cases, it is preferable to put the ocpidev-related attributes in a separate file (leaving the OAS a purely runtime-environment application specification for use with ocpirun). In this latter case, the runtime and development attributes can be in a separate XML file named <appname>-app.xml, which is only used by the ocpidev command for the build, run, and clean functions.

The following table lists these ocpidev-related attributes in the OAS. There are no child elements for development purposes:

Table 19: Attributes in the Application Development XML File

Attribute Name	Description
Options for development and building
FileName	The name of the primary source file for an ACI application. Defaults to the application’s name: the name of its directory. This value is without any language suffix such as .cc, .cxx, .c etc.
OtherMains	The names of other main source files, without language suffixes. Used for related executables to be built in this same directory.
SourceFiles	Other source files to be compiled and linked with the executables built in These file names include suffixes, which may be .c, .cc, .cxx, .cpp.
PrereqLibs	Installed prerequisite library names that are required to build the executable(s) from the source files here. E.g. liquid, a DSP function library that is installed with OpenCPI. If the executables are built statically (the default), the statically-linked version of the library will be used; otherwise, the dynamically-linked version will be used.
PackageName	The package name for this application.
PackageID	The full packageID for this application.
ExcludePlatforms	Platforms that should not be built in this directory.
Options for runtime/execution in the development environment, using ocpidev run
NoRun	If set, indicates that this application cannot be run automatically using ocpidev run. When the run is attempted, a message is printed and the exit status is 0 (no error indicated).
RunBefore	Command arguments on the command line before the executable name (e.g. environment variable settings).
RunArgs	Command arguments immediately following the executable name (e.g. command line options, to ocpirun).
RunAfter	Command arguments at the end of the command line.
Options for cleaning in the development environment, using ocpidev clean
CleanFiles	Files and directories to be removed when the application is cleaned.

Executing/Running Applications in Projects

All applications in a project may be run in sequence using the command:

ocpidev run applications

Run an OpenCPI Project’s Applications.

Usage:

$ ocpidev run applications [OPTIONS] [Application]

Arguments:

• [Application]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• --after TEXT: Specify the argument to insert at the end of the execution command line. May be used more than once.

• --before TEXT: Specify the argument to insert before the command. May be used more than once.

• --run-arg TEXT: Specify the argument(s) to insert immediately after the ACI executable or the ocpirun command.

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

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

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

• --help: Show this message and exit.

from anywhere in the project directory.

This will run all applications, one after the other, with no arguments specified. To run a particular ACI application, you can either run ocpidev run in the application’s directory, or from elsewhere in the project directory, you can use:

ocpidev run applications

Run an OpenCPI Project’s Applications.

Usage:

$ ocpidev run applications [OPTIONS] [Application]

Arguments:

• [Application]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• --after TEXT: Specify the argument to insert at the end of the execution command line. May be used more than once.

• --before TEXT: Specify the argument to insert before the command. May be used more than once.

• --run-arg TEXT: Specify the argument(s) to insert immediately after the ACI executable or the ocpirun command.

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

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

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

• --help: Show this message and exit.

This also works with simple XML applications (those without their own directories), whether <appname> includes the .xml suffix or not.

When applications are run using ocpidev, the OCPI_LIBRARY_PATH environment variable, if not set already, will be automatically set to search the project’s own artifacts/ subdirectory (where all artifacts built in the project reside), as well as the exported artifacts from any of the projects this project depends on.

Running all the applications in a project with default arguments is normally used for test purposes. If an application cannot be run with default arguments or needs to interact with a user, it should not fail (with non-zero exit status), but simply avoid running and print a message that it is not being run because it cannot run in this simple way with default arguments. This allows for an easy “test run of all applications in the project”. Setting the noRun attribute to non-empty in the <application>.xml file avoids running the application, but prints a message and returns a zero exit status indicating success.

Several ocpidev run options to change how the application is run in the project environment are described in the following table. For each, there are also XML attributes as described in the above table. While the XML attributes are lists, these ocpidev run options specify one value, but may be used more than once. The XML attributes act as defaults, with the ocpidev run options overriding them.

Table 20: Options for ocpidev when Running Applications

Command Option	Description
--before	Arguments to insert before the ACI executable or ocpirun, such as environment settings or prefix commands like time or valgrind. The XML equivalent attribute is runBefore
--run-arg	Arguments inserted just after the ACI executable or ocpirun, such as ocpirun options like -v or -m -or -p. The XML equivalent attribute is runArgs.
--after	Arguments to insert at the end of the execution command line. The XML equivalent attribute is runAfter.

For XML applications, these options (or XML attributes) are applied to the underlying ocpirun command using the following pattern:

<befores> ocpirun <run-args> <xml-OAS-file> <afters>

For ACI C++ applications, the pattern is:

<befores> <executable> <run-args> <afters>

Tip

When running applications with ocpidev run, run-args can be attached to the --run-arg option:

$ ocpidev run application myapp --run-arg=-v --run-arg=-d --run-arg=-Pxsim
$ ocpidev run application myapp --run-arg="-v -d -Pxsim"

which will, for XML apps, perform:

$ ocpirun -v -d -Pxsim myapp

If the runArgs XML attribute was set as: runArgs='-v -d -Pxsim', the same effect would result by just running:

$ ocpidev run application myapp

HDL Assemblies in Projects

HDL assemblies may also be created in projects.

Creating an HDL Assembly

ocpidev create hdl assembly

Create an OpenCPI HDL Assembly.

Usage:

$ ocpidev create hdl assembly [OPTIONS] NAME

Arguments:

• NAME: [required]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• --exclude-platform Platform: Do not allow building asset for specified platform. May be used more than once.

• --only-platform Platform: Only allow building asset for specified platform. May be used more than once.

• --exclude-target HDL Target: Do not allow building asset for specified HDL target. May be used more than once.

• --only-target HDL Target: Only allow building asset for specified HDL target. May be used more than once.

• --help: Show this message and exit.

Within a project, HDL assemblies are created in the hdl/assemblies/ directory in the project. Similar to applications, that directory has a standard XML file named assemblies.xml, and it can contain a setting of the Assemblies attribute when the default behavior, of all assemblies being built in alphabetical order, is not desired.

Each assembly is created as an XML file in its own directory. Thus creating the HDL assembly whose name is myassy, would create the myassy.xml file in the hdl/assemblies/myassy directory. After editing this file to describe the required worker instances and connections, artifacts based on this assembly can be created using the ocpidev build.

Tip

When building from within an assembly’s directory itself, you can simply use:

$ ocpidev build

Tip

To build all assemblies in a project, you can issue the following command from anywhere within the project’s directory:

ocpidev build hdl assemblies

Build all OpenCPI Hdl Assemblies in a Project or Library.

Usage:

$ ocpidev build hdl assemblies [OPTIONS] [HDL Assembly]

Arguments:

• [HDL Assembly]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• --hdl-platform HDL Platform: HDL Platform(s) to apply the command for.

• --doc-only: Only build docs.

• --no-doc: Do not build docs.

• --artifacts-only: Clean up intermediate build files.

• -j, --n-jobs INTEGER RANGE: The max number of parallel jobs to allow. [default: 1; 1<=x<=48]

• --streamline-build: Skip checkpoints when building assemblies.

• --accumulate-errors: Do not stop builds after a failure.

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

The resulting FPGA artifact files, with the suffix .bitz, are created in target-specific directories with the prefix container-, created under the assembly’s directory.

Details about this artifact building process can be found in HDL Assemblies for Creating Bitstreams/Executables.

Deleting an HDL Assembly

ocpidev delete hdl assembly

Delete an OpenCPI HDL Assembly.

Usage:

$ ocpidev delete hdl assembly [OPTIONS] [HDL Assembly]

Arguments:

• [HDL Assembly]

Options:

• -p, --project Project: Specify the Project that the asset resides in.

• -f, --force

• --help: Show this message and exit.

Once the HDL assemblies are built, resulting in the .bitz artifact files, applications can use them as long as they are accessible using the OCPI_LIBRARY_PATH environment variable. If applications are run using ocpidev run, the library path will automatically find the built assemblies in the same project as the application or in projects that the application’s project depends on.